Troubleshooting

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=lite has been removedlite was removed outrightUse RELATA_PROFILE=free
FATAL on a RELATA_* valueStrict parsing rejects malformed valuesCorrect the value — typos no longer fall back to defaults
server/cluster refuses to startAuth required on these profilesSet RELATA_BEARER_TOKEN
address already in usePort 9090 (or a door port) is takenChange RELATA_PORT / RELATA_<DOOR>_PORT, 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.

Doors won't connect / not reachable

Every protocol door is opt-in and off by default, and on free the server binds to loopback only.

SymptomCauseFix
Connection refused to a doorDoor not enabledSet RELATA_<DOOR>_ENABLE=true (e.g. RELATA_S3_ENABLE, RELATA_MONGO_ENABLE)
Reachable locally, not from another host/containerfree binds 127.0.0.1RELATA_HTTP_BIND=0.0.0.0 (no license needed); in Docker also -p publish the port
S3 403 SignatureDoesNotMatchPlaintext bearer sent where SigV4 is requiredSign with SigV4; the secret defaults to the bearer token — set RELATA_S3_SECRET_KEY to customise
pgwire / MCP 401 UnauthorizedMissing/invalid bearerSend Authorization: Bearer $RELATA_BEARER_TOKEN
/debug/pprof/* returns 404 or 401Profiling is off by default and admin-gatedRELATA_PPROF_ENABLE=true + RELATA_ADMIN_TOKEN, then send the admin bearer

Write rejected — 402 Payment Required

You hit the Free-tier 10 GB storage cap (the only paid limit).

curl -s localhost:9090/metrics | grep relata_store_total_stored_bytes
  • Reduce or expire old data, or activate a license to lift the cap.
  • A soft warning is logged at 90% (9 GB); 402 is the hard stop at 10 GB.

403 on multi-tenant writes/reads

Under RELATA_TENANCY_MODE=multi, tenant-less requests fail closed to prevent cross-tenant leakage.

  • Send the caller's tenant: header X-Relata-Tenant-Id: <org> (or a verified OIDC org claim).
  • session_id is not a security boundary — the tenant (org) is.
  • In genuine single-tenant dev, keep RELATA_TENANCY_MODE=single.

Cluster reads return 206 Partial Content

A fan-out read couldn't reach every peer but returned what it could — Relata tells you honestly instead of a silent, incomplete 200.

  • Check CLUSTER_PEERS — every peer URL must be reachable from the coordinator.
  • The response body carries _relata_warnings listing the failed peer(s).
  • Writes to the wrong shard are blocked by the CROSS_SHARD_WRITE guard — verify branch/shard routing.

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.
  • Multi-tenant scope: in single mode, 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