Troubleshooting

Symptom, check, fix for the problems the install and the first runs meet most often.

Start at the top and stop at the first step that fails:

The backend is up: curl http://127.0.0.1:5566/api/health
Its dependencies are ready: curl http://127.0.0.1:5566/api/readiness
Sign-in works in the browser, starting from http://127.0.0.1:5566
The run's own logs, in Activity
The containers' logs: docker compose logs backend --tail=200

For an API error code, see Error codes.

The backend does not start

Check: docker compose logs backend --tail=100

Cause	Fix
No `AUTH_MODE`, or its provider values are missing	Run `./install.sh wizard` (or `./scripts/env_wizard.sh`) and choose a profile
Outside local: `ALLOWED_HOSTS` or `CORS_ALLOWED_ORIGINS` missing	Set both, for example `ALLOWED_HOSTS=app.example.com` and `CORS_ALLOWED_ORIGINS=https://app.example.com`
Outside local: the default `postgres:postgres` DSN or a placeholder secret	Set a real DSN and replace `changeme`-style secrets

If the database itself is not usable, the backend starts in setup mode: it logs SETUP MODE: the database could not be initialized, the data routes answer 503, and the setup wizard shows the reason and how to repair it.

A change to `.env` does nothing

A container keeps the environment it was created with. After any .env edit:

docker compose up -d

./scripts/install-doctor.sh names containers whose configuration differs from the compose file.

Backend and worker restart after the wizard

Symptom: database "…" does not exist in a loop. Cause: an old APP_DB_POSTGRES_DSN exported in your shell overrides the new .env.

unset APP_DB_POSTGRES_DSN
docker compose up -d --force-recreate backend worker

Symptom	Fix
`401` with "Authentication required" or "Session expired or invalid"	Sign in again from `http://127.0.0.1:5566`
ZITADEL shows `Errors.App.NotFound`	`ZITADEL_CLIENT_ID` names no app in this ZITADEL; on a fresh local setup run `./install.sh local` again
Signed in, but `403` "user is not authorized for this deployment"	Your role has no access mapping; check System, Access mapping, and that the provider puts the role into the token
You opened `localhost:5566`	It redirects to `127.0.0.1:5566` so the callback matches; start there

More: Sign-in with ZITADEL or Cognito.

Config does not parse

Check:

douklar config validate --config config/simple-config.ini

Fix the rows it names in config/simple-config.ini, then generate config/sync.yaml again:

douklar config generate --config config/simple-config.ini --format yaml --output config/sync.yaml

Queued runs wait

Symptom: the worker logs Job claim failed. The worker could not reach the database to claim the job; it retries with a growing wait, up to 30 seconds, and logs Job claim recovered when the database answers. If the warning repeats with no recovery, check the database first: docker compose logs postgres --tail=200.

CodeCommit Sync shows Errored

Symptom: System, Installation, Plugins reports CodeCommit as errored with git-remote-codecommit was not found in PATH. Rebuild the images:

docker compose up -d --build backend worker

Start again from nothing

./install.sh uninstall --local --yes
./install.sh local

The uninstall removes the containers, the compose volumes and the network, and moves .env to .env.bak. The volumes hold all persistent state (the database, sessions and encrypted credentials, sync output and reports), so this deletes it.

Count this visit?