Reference

Troubleshooting

Solutions to the most common issues encountered when running DevPanel.

Dashboard not reachable after install

The dashboard is not accessible at http://localhost:33000.

→Check that Docker is running: docker info

→Check that the containers started: devpanel status

→

Check for port conflicts — another process may be using port 33000. Reinstall with a different port: devpanel install --port 8080

→Check DevPanel logs for startup errors: devpanel logs

Server stays "pending" / agent not connecting

After adding a server, it stays in the pending state and never goes online.

For local servers: DevPanel launches the agent container automatically. It can take ~30 seconds. If it stays pending:

→Verify the agent container is running: docker ps | grep devpanel-agent

→Check agent logs: docker logs devpanel-agent

→Make sure Docker socket is accessible: ls -la /var/run/docker.sock

For remote servers: You must start the agent manually. Run this on the remote server:

bash

docker run -d --restart unless-stopped \
  --name devpanel-agent \
  -p 33002:33002 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/your-org/devpanel-agent:latest

Then check that port 33002 is reachable from the DevPanel host.

Service fails to deploy

Deployment starts but the service never reaches "running" status.

Invalid compose YAML

Use the Source tab to view the compose file. Validate it with: docker compose -f compose.yml config

Missing environment variables

Check the Env tab — variables referenced in the compose file must be defined there.

Port already in use

If host port binding fails, change the host port in the compose file or Overview tab.

Image pull failure

Check container logs in the Logs tab. Private registries may need auth credentials in the compose file.

Volume mount errors

Host paths in bind mounts must exist on the server. Check the Volumes tab and create the directory if needed.

Custom domain not accessible

A domain was added but the URL returns an error or times out.

No host port set

The Cloudflare tunnel routes to localhost:<hostPort>. Set a host port in the service's Overview tab, then re-add the domain.

Tunnel credentials missing

Go to Settings → Cloudflare and verify that API Token, Account ID, and Tunnel ID are all filled in.

Service not running

The tunnel will connect but the upstream (localhost:<hostPort>) must be running. Check service status in the Overview tab.

DNS not propagated

CNAME records usually propagate within seconds with Cloudflare proxy enabled. If it takes longer, check the DNS tab in the Cloudflare dashboard.

Hostname not in your CF account

DevPanel validates that the hostname belongs to a zone in your Cloudflare account. Ensure the domain is added to your CF account.

Cloudflare credential errors

DevPanel shows "Cloudflare credentials not configured" or domain add fails.

→

Confirm all three credentials are saved: API Token, Account ID, Tunnel ID (Settings → Cloudflare).

→

Verify the API token has the correct permissions: Account · Cloudflare Tunnel · Edit, Zone · DNS · Edit, Zone · Zone · Read.

→

Make sure the Tunnel ID is the UUID from Zero Trust → Networks → Tunnels (not the tunnel name).

→

Check that the Account ID matches the account that owns the tunnel and the domain's zone.

Forgot admin password

You can reset any user's password directly from the CLI.

bash

devpanel reset-admin-pass

Follow the prompts to enter the account email and a new password (min. 8 characters). Leave the email blank to reset the first admin account.

Running out of disk space

Docker volumes and unused images can accumulate over time.

bash

# Remove unused Docker images, stopped containers, and dangling volumes
docker system prune -f

# Check disk usage by image
docker system df

Starting fresh (full reset)

If DevPanel is in a broken state and you want to wipe everything and start over:

Warning — irreversible

This permanently deletes all projects, services, and data. Back up first with devpanel backup.

bash

# Back up first
devpanel backup

# Then reset
devpanel reset

Still stuck?

Open an issue on GitHub with the output of devpanel status and devpanel logs.

PreviousApp Templates