Skip to main content
Common failure modes and their fixes. If none of these match, open a GitHub Discussion with the output of observal auth status and relevant logs from docker compose logs.

Install and CLI

"Connection failed. Is the server running?"

The CLI cannot reach the API. Check:
If server_url is wrong:

"System already initialized" when logging in

The server already has users, so bootstrap is disabled. Use observal auth login with an email + password or an API key, not a fresh bootstrap flow.

Docker and networking

port is already allocated

Another process is on one of Observal’s default ports. Remap host ports:
Full list in Ports and volumes.

Service stuck in starting

The API depends on Postgres, ClickHouse, and Redis being healthy. Check each:
Common causes:
  • ClickHouse stuck during initial CREATE TABLE. Restart it once the healthcheck passes on other DBs
  • CLICKHOUSE_PASSWORD mismatch between services and API config

Services restart in a loop

Check logs (docker compose logs -f <service>). Three frequent causes:
  • Memory limit too tight. Bump limits in docker-compose.yml
  • Corrupt volume. Wipe and restore from backup
  • Config error introduced during an upgrade. Roll back

Auth

Admin forgot password

There is no reset code to look up. An admin resets the account directly:
Hand the printed password to the user out-of-band; they must change it at their next sign-in.

OAuth login fails with redirect_uri_mismatch

The IdP doesn’t have the right redirect URI registered. Add:
with FRONTEND_URL set to your real external URL (scheme and host must match exactly).

All users logged out after restart

Likely the apidata volume was recreated, so the JWT signing keys are new. Restore the apidata volume from backup, or accept that all sessions are invalid and everyone has to log in again.

Telemetry

Nothing in the dashboard

Run through, in order:
If hooks are missing, run observal doctor patch --harness <harness>. If sessions still are not arriving, check ~/.observal/telemetry_buffer.db; growth indicates pending session delivery rather than silent loss.

ClickHouse not receiving data

Check the CLICKHOUSE_URL the API is using:
The source Compose default is clickhouse://default:clickhouse@observal-clickhouse:8123/observal. Mismatches typically happen after changing CLICKHOUSE_PASSWORD without updating the URL. Server-package installs use CLICKHOUSE_URL_FILE=/run/secrets/clickhouse_url, a hashed ClickHouse user configuration, and a separate health-check password file. Confirm the file is mounted without printing it:
Verify ClickHouse itself:

Web UI

Blank white page

Frontend is still building. Check:
For local dev (running Vite outside Docker), the dev server proxies /api to http://localhost:8000 (see web/vite.config.ts); confirm your backend is reachable there.

Login redirects back to login immediately

Browser cookies aren’t being set. Usually one of:
  • FRONTEND_URL doesn’t match the URL you’re hitting.
  • CORS_ALLOWED_ORIGINS doesn’t include your frontend origin.
  • You’re on HTTP behind a proxy that’s setting secure cookies. Terminate TLS at your proxy and keep FRONTEND_URL=https://....

Where to get more help

  • Logs: docker compose -f docker/docker-compose.yml logs -f
  • Health: curl http://localhost/health
  • Status: observal auth status
  • Community: GitHub Discussions
  • Bugs: GitHub Issues. Please use Discussions for questions, Issues only for confirmed bugs