# 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:

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

For an API error code, see [Error codes](/docs/douklar/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:

```bash
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`.

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

## Sign-in fails

| 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](/docs/douklar/sign-in-zitadel-or-cognito#check-the-setup).

## Config does not parse

**Check:**

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

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

```bash
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:

```bash
docker compose up -d --build backend worker
```

## Start again from nothing

```bash
./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.

Source: https://douklar.app/docs/douklar/troubleshooting (Douklar docs, last checked 2026-10-23)