Troubleshooting
server/cluster profiles and the old unversioned routes describe 2.5.8. In 3.0 an old unversioned path answers 404. See HTTP route restructure. For restart and WAL problems on a large store see Capacity planning and WAL retention.Relata fails closed and loud: it refuses to start on a bad configuration rather than silently degrading. Most issues are a single env var. If a symptom isn't here, see Error Codes and Environment Variables.
Startup failures (FATAL)
Relata exits at startup with a clear FATAL line. Common causes:
| Symptom | Cause | Fix |
|---|---|---|
RELATA_PROFILE rejected | lite, server and cluster are removed; only free is accepted | Unset RELATA_PROFILE or set free; configure posture through bind address, TLS and tokens |
FATAL on a RELATA_* value | Strict parsing rejects malformed values | Correct the value — typos no longer fall back to defaults |
| Refuses to start with no authentication configured | Auth is mandatory on every node | Set RELATA_BEARER_TOKEN and RELATA_ADMIN_TOKEN (or the loopback-only dev opt-in) |
address already in use | Port 9090 (or the admin port 9091) is taken | Change RELATA_PORT / RELATA_ADMIN_BIND, or stop the other process |
data dir is locked by another process | Only one relata serve per data dir (exclusive flock) | Stop the other instance or use a different RELATA_DATA_DIR |
Tip: bump verbosity to see exactly where startup stalls —
RELATA_LOG_LEVEL=debug relata serve.
Not reachable or 401
The server binds to loopback by default. The PostgreSQL, S3, MongoDB, Redis, ClickHouse, Neo4j, Bolt and Arrow Flight listeners are retired in 3.0, so connection errors from those clients are expected; see Migrating from retired doors.
| Symptom | Cause | Fix |
|---|---|---|
| Reachable locally, not from another host or container | The node binds 127.0.0.1 | Set RELATA_HTTP_BIND=0.0.0.0:9090, which also requires TLS (or RELATA_PLAINTEXT_OK=true behind a proxy); in Docker also -p publish the port |
401 Unauthorized on the data plane | Missing token, or the bootstrap RELATA_BEARER_TOKEN was sent | Send a registry-minted token (POST /admin/tokens on the loopback admin listener) as Authorization: Bearer <token> |
/admin/* answers 404 on port 9090 | The admin surface is on its own loopback listener | Use 127.0.0.1:9091 from the host or a sidecar |
/debug/pprof/* returns 404 or 401 | Profiling is off by default and admin-gated | RELATA_PPROF_ENABLE=true + RELATA_ADMIN_TOKEN, then send the admin bearer |
relata_audit_chain_valid == 0
The tamper-evident audit chain detects a modified/deleted entry. Treat as a security event: isolate the node, preserve the WAL directory, and investigate. See Observability.
Queries return nothing (or are slow)
AS OFscans: temporal reads scan + bloom-prune segments today (a version index is landing to make this O(log n)). Narrow the time window or type.- Global scans: a global sanity gate may block broad scans — set
RELATA_GLOBAL_SCAN_ALLOWED=trueonly for trusted diagnostics. - Inspect the plan with
EXPLAIN ANALYZE <query>(per-operator timing).
Getting more detail from logs
RELATA_LOG_LEVEL=debug RELATA_LOG_FORMAT=json relata serve- Levels:
trace·debug·info·warn·error. - Every error response carries a
request_id(RFC 7807application/problem+json) — grep the logs/audit chain for it to trace a user-visible failure end-to-end.
Still stuck
- Error Codes — every
codethe API returns. - Environment Variables — the full
RELATA_*surface. - GitHub — relatadb · or see Editions and limits for Relata Enterprise DB.