Dev console troubleshooting

Use this page when ./console fails to start the stack, systemd units are unhealthy, or Deno vs Workers instance mode behaves unexpectedly. For database schema issues, see Database troubleshooting.

Console will not start

Verify Deno runtime: /opt/turbopanel/vendor/deno/current/deno --version
First run may require sudo to create /opt/turbopanel/vendor — re-run ./console after granting privileges.
Pull latest in each sibling checkout on the host (they are mounted into the guest). From ~/dev inside the guest, re-run ./console after updating.

Dev stack will not start

Open the Services area in ./console and check unit states.
Follow logs with L on a service row (external pager), or tail /var/log/turbopanel/.
Verify Docker is running: docker version (Postgres runs in Docker).
Confirm the daemon checkout exists: ~/turbopaneld/.
On a fresh guest the console auto-bootstraps the daemon on launch; otherwise run Developer → Converge / re-converge.

Instance runtime not switching

Use the Services area in ./console to switch between Deno and Workers runtime.
Both modes run under turbopanel-instance.service — Workers mode starts wrangler via scripts/workers-serve.sh in the instance checkout; no manual pnpm dev is needed.
Deno mode requires /run/turbopanel to exist and turbopanel-instance.service to be active.

Port conflicts

Symptom: address already in use in journal logs.
Fix: stop the conflicting process or change CADDY_PORT / CADDY_HTTP_PORT in /etc/turbopanel/daemon.env and restart Caddy.
Example (Unix): lsof -ti :8443 | xargs kill or lsof -ti :8880 | xargs kill (replace with the port from the error).

Dev plaintext entrypoint (http://localhost:8880)

Co-located dev exposes a plaintext mirror of the control plane at http://<host>:8880. It is gated by TURBOPANEL_DEV_HTTP_CONTROL_PLANE=1 (injected automatically when the dev user is configured) and is not enabled on managed or production installs. Both TURBOPANEL_INSTANCE_RUNTIME=deno and =workers use the same Caddy proxy, so :8880 mirrors every route on :8443 for either runtime.

403 on :8880: confirm TURBOPANEL_DEV_HTTP_CONTROL_PLANE=1 is set on the Caddy/instance env (Ansible sets this on co-located dev).
Smoke test: curl http://localhost:8880/api/health (compare with curl -k https://localhost:8443/api/health).
Daemon attach without CA: point co-located daemon config at http://<host>:8880 instead of https://<host>:8443 during local troubleshooting.

Caddy 502 on https://localhost:8443 or http://localhost:8880

Ensure turbopanel-instance.service and turbopanel-ui.service are active before Caddy serves traffic.
Deno mode: confirm /run/turbopanel/instance.sock exists and is group-writable.
Workers mode: wrangler must bind 0.0.0.0 (see wrangler.jsonc dev.ip) if Caddy reaches it over TCP.
The :8880 plaintext entrypoint shares the same upstreams as :8443; a 502 on one usually means the same backend issue on both.

TLS / certificate warnings

Trust the platform CA bundle at /var/lib/turbopanel/tls/ca-bundle.pem (or fetch from GET /api/daemon/v1/instance/ca) in your OS or browser.
If certs are missing, re-run Developer → Converge / re-converge in ./console.

Schema sync failures

Run ./scripts/sync.sh --force from the dev checkout.
Ensure Postgres is healthy (docker ps / Services area in the dev console).
See Database troubleshooting.

Expo / UI not loading

Confirm turbopanel-ui.service is active.
Caddy proxies non-API traffic to Expo when TURBOPANEL_UI_MODE=dev.

Platform checkouts missing

Clone all six sibling repos on the host before vagrant up so VirtFS/VirtioFS mounts are populated. If a mount looks empty inside the guest, confirm the host paths exist beside dev/ and remount with vagrant reload.

Dev plaintext entrypoint (http://localhost:8880)

Caddy 502 on https://localhost:8443 or http://localhost:8880

On this page