Troubleshooting

Relata DB 3.0
Start-up and error messages for the retired doors, the 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:

SymptomCauseFix
RELATA_PROFILE rejectedlite, server and cluster are removed; only free is acceptedUnset RELATA_PROFILE or set free; configure posture through bind address, TLS and tokens
FATAL on a RELATA_* valueStrict parsing rejects malformed valuesCorrect the value — typos no longer fall back to defaults
Refuses to start with no authentication configuredAuth is mandatory on every nodeSet RELATA_BEARER_TOKEN and RELATA_ADMIN_TOKEN (or the loopback-only dev opt-in)
address already in usePort 9090 (or the admin port 9091) is takenChange RELATA_PORT / RELATA_ADMIN_BIND, or stop the other process
data dir is locked by another processOnly 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.

SymptomCauseFix
Reachable locally, not from another host or containerThe node binds 127.0.0.1Set 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 planeMissing token, or the bootstrap RELATA_BEARER_TOKEN was sentSend a registry-minted token (POST /admin/tokens on the loopback admin listener) as Authorization: Bearer <token>
/admin/* answers 404 on port 9090The admin surface is on its own loopback listenerUse 127.0.0.1:9091 from the host or a sidecar
/debug/pprof/* returns 404 or 401Profiling is off by default and admin-gatedRELATA_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 OF scans: 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=true only 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 7807 application/problem+json) — grep the logs/audit chain for it to trace a user-visible failure end-to-end.

Still stuck