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, or an apply that reports port 80 is held by <process>.
:8443 is the control-plane listener and its port is fixed. Stop the conflicting process.
Port 80 is claimed for a control-plane name only while Let's Encrypt is issuing or renewing. port 80 is held by nginx (or another process name) means that process must release port 80 before the apply can continue. Hosting Caddy may already hold it for hosted sites; that holder is expected.
Example (Unix): lsof -ti :8443 | xargs kill (replace with the port from the error).

Caddy 502 on https://localhost:8443

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.
Trust the Platform CA (/var/lib/turbopanel/tls/ca-bundle.pem, or GET /api/daemon/v1/instance/ca). A browser warning on a LAN name is the Platform CA leaf. Open https://localhost:8443.

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.

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.