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.
• Update the checkout: sh scripts/develop.sh from inside the dev repo checkout (~/dev).

Dev stack will not start

• Open the Status area in ./console and check unit states.
• Follow logs from the Actions area (Follow logs).
• Verify Docker is running: docker version (Postgres runs in Docker).
• Confirm the daemon checkout exists: ~/daemon/.
• If the daemon repo is missing, use Install daemon in the Actions area first, then Start dev stack.

Instance runtime not switching

• Use the Instance area in ./console (Switch to Deno Mode / Switch to Workers Mode).
• Workers mode requires pnpm dev running manually in ~/instance/.
• 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 ~/instance/certs/ca.crt (or fetch from GET /api/daemon/v1/instance/ca) in your OS or browser.
• Re-run the instance-certs Ansible role or pnpm cert:generate in the instance checkout if certs are missing.

Schema sync failures

• Run ./scripts/sync.sh --force from the dev checkout.
• Ensure Postgres is healthy (docker ps / Services section in the developer 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

The console installs only the daemon repo. Instance, UI, and website are installed by the daemon via Ansible when Start dev stack runs. If checkouts are incomplete, restart the daemon unit and check journalctl -u turbopaneld -f for Ansible errors.

Related

• Local development
• Development architecture
• Deployment troubleshooting