Startup and readiness

Use this page when Oriel starts but is not ready, or when the process exits before serving traffic.

Symptoms

• /healthz returns ok but /readyz fails.
• The process exits during startup.
• systemd restarts oriel.service.
• Compose reports oriel unhealthy.

Checks

Run:

oriel --config /etc/oriel/oriel.toml doctor

Check service logs:

journalctl -u oriel.service -n 200

For compose:

cd deploy/compose
docker compose -f local.yml logs oriel
docker compose -f local.yml logs oriel-migrate

Common causes

Cause	Signal	Fix
PostgreSQL unreachable	ORL-5003 or startup connection error	Fix metadata.dsn, network, credentials, or database state.
ClickHouse unreachable	ORL-5001	Fix clickhouse.dsn, network, credentials, or ClickHouse state.
Valkey unreachable	ORL-5005 or startup connection error	Fix valkey.dsn, network, credentials, or Valkey state.
Schema mismatch	ORL-5002 on /readyz	Run oriel migrate up with the service config.
Plaintext non-loopback bind	Startup error from listener guard	Configure TLS, bind loopback, or intentionally set server.insecure = true.
Bad OIDC config	ORL-3004	Fix provider slug, icon, group map, public_url, or redirect_url.

Recovery

Prefer this order:

1. Fix configuration and dependencies.
2. Run oriel doctor.
3. Run oriel migrate status.
4. Run oriel migrate up if pending migrations exist.
5. Restart Oriel.

Avoid repeated restarts before dependency and schema checks are clean.

See Migrations for ORL-5002 and Configuration for listener and DSN settings.