Troubleshooting

Start with the doctor. It checks configuration and every dependency and prints a stable code for each problem:

./deploy/compose/quavon doctor
./deploy/compose/quavon status
./deploy/compose/quavon logs <service>     # api, worker, init, postgres, valkey, caddy, sandbox-runner

On Kubernetes use kubectl logs for the same components. Fixes for every code are in doctor.md.

Common symptoms

Symptom	Check	Codes
Setup page does not open, browser shows a certificate error	DNS of the domain, ports 80/443, quavon logs caddy; ACME may still be issuing	QD501, QD502
Sign-in with GitHub fails with a redirect error	Callback URL <PUBLIC_URL>/auth/github/callback in the app settings	QD605
Nobody is instance admin, or the GitHub App is broken	quavon break-glass (operations.md)	QD901, QD603
Webhooks do not arrive	Delivery log of the app on the code host; webhook URL <PUBLIC_URL>/webhooks/github; the code host must reach PUBLIC_URL with a trusted certificate. 401 means unknown app or wrong secret, 429 too many failed deliveries. Other code hosts: providers.md	QD606, QD502
Webhooks arrive but reviews do not start	Review mode of the repository (off does nothing; shadow stores reviews without posting; approval waits in the approvals inbox); quavon logs worker; worker reaches Valkey	QD801, QD301
Reviews fail with model errors	Language model credentials of the tenant (Test connection), base URL, budget alerts, quavon logs worker	–
Reviews post nothing although they completed	Approvals inbox (approval mode); app permissions on the code host	QD603
Deterministic checks are skipped or failed	Runner health and smoke test (sandbox.md)	QD951–QD958
Bot ignores @codelotse commands	Chat mode, permissions and syntax (commands.md)	–
api or worker restarts at start-up	The first lines of quavon logs api list every invalid variable	QD101
Stored credentials stopped working after a restore or key change	Encryption key and previous keys	QD403, QD604
After an upgrade the API reports missing migrations	quavon logs init (upgrade.md)	QD205
GitHub rejects the app intermittently	Host clock	QD701

Codes

Code	Symptom	Section
QD001	A check timed out	General
QD002	A check failed unexpectedly	General
QD003	A check was skipped because an earlier one failed	General
QD101	Services do not start: invalid configuration	Configuration
QD201	PostgreSQL not reachable	Database
QD202	PostgreSQL rejects a role password	Database
QD203	TLS to PostgreSQL fails	Database
QD204	Other database error, for example missing database	Database
QD205	Migrations not applied	Database
QD206	Schema not initialised	Database
QD207	pgvector missing, semantic code search off	Database
QD301	Valkey not answering	Valkey
QD302	Valkey rejects the password	Valkey
QD401	All encrypted values readable (ok)	Encryption keys
QD402	Values still on a previous key	Encryption keys
QD403	Values cannot be decrypted	Encryption keys
QD501	PUBLIC_URL is not https	Public URL
QD502	PUBLIC_URL not reachable from inside the stack	Public URL
QD601	No GitHub App registered	GitHub
QD602	GitHub host not reachable	GitHub
QD603	GitHub rejects the app JWT	GitHub
QD604	App credentials cannot be decrypted	GitHub
QD605	Reminder: sign-in callback URL	GitHub
QD606	Reminder: webhook URL	GitHub
QD701	Clock skew against GitHub	Clock
QD702	Time could not be read from GitHub	Clock
QD801	Outbox jobs waiting longer than 5 minutes	Outbox
QD901	No instance admin	Instance admin
QD951	No sandbox runner reports health	Sandbox
QD952	Runner uses the insecure backend	Sandbox
QD953	Firecracker without /dev/kvm	Sandbox
QD954	Runner backend unhealthy	Sandbox
QD955	Runner shares a host with API and worker (enterprise edition)	Sandbox
QD956	Sandbox image classes missing	Sandbox
QD957	Escape smoke test failed, missing or outdated	Sandbox
QD958	Smoke test did not finish in time	Sandbox

Getting help

When you report a problem, attach quavon doctor --json and the relevant log lines. Both are free of secrets and tokens; review them for repository names before sharing. Security issues go to the process in SECURITY.md.