--- title: Troubleshooting description: "relate, the embedded Cypher graph database (relatedb.ai): Go from a relate error message or exit code to its fix: symptom tables that link each error to its reference entry and to the guide that resolves it." type: how-to surfaces: - cli - cypher - http - bolt - mcp - agents status: stable verified: 0.1.2 verified_by: - cli canonical_url: https://relatedb.ai/docs/guides/operate/troubleshooting/ prerequisites: - get-started/install related: - reference/errors - reference/cli/exit-codes-and-errors - guides/operate/crash-and-recovery - guides/operate/two-processes-one-store last_updated: 2026-11-09 --- # Troubleshooting Go from a relate error message or exit code to its fix: symptom tables that link each error to its reference entry and to the guide that resolves it. > Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2 This guide shows you how to get from an error to its fix. Find the message in the tables, follow the reference link for the error's cause and exit code, and follow the fix link for the steps. Every row points at a page; the [errors reference](https://relatedb.ai/docs/reference/errors/) holds the complete entry for each one. ## Prerequisites - The error's text from stderr and the command's [exit code](https://relatedb.ai/docs/reference/glossary/#exit-code). - `relate` on your `PATH` ([Install relate](https://relatedb.ai/docs/get-started/install/)). - To follow along, the shared example graph as `team.rl`: ```bash verify cat > team.cypher <<'EOF' CREATE (ada:Person {name: 'Ada', role: 'engineer'}), (grace:Person {name: 'Grace', role: 'engineer'}), (noor:Person {name: 'Noor', role: 'maintainer'}), (relate:Project {name: 'relate', language: 'Rust'}), (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}), (ada)-[:WORKS_ON {since: 2024}]->(relate), (grace)-[:WORKS_ON {since: 2023}]->(relate), (grace)-[:WORKS_ON {since: 2022}]->(tck), (noor)-[:MAINTAINS]->(relate), (ada)-[:KNOWS]->(grace); EOF relate query --database ./team.rl < team.cypher ``` ## Read the error Run the failing command again with `--mode envelope` and print the exit code. In this example, the [store](https://relatedb.ai/docs/reference/glossary/#store)'s name is misspelled, `tema.rl`, so a read-only open finds nothing to open: ```bash verify relate --database ./tema.rl --read-only --mode envelope "MATCH (p:Person) RETURN count(p) AS people" echo "exit=$?" ``` The path starts with the working directory, shown as ``. The first line is stderr, the second the [error object](https://relatedb.ai/docs/reference/glossary/#error-object) on stdout: ```text Failed to open Relate: storage error: database not found: /tema.rl {"error":{"code":"fatal_error","exit_code":1,"kind":"storage","message":"storage error: database not found: /tema.rl","retryable":false}} exit=1 ``` The error object's `code` is the class and `exit_code` the exit code, `kind` narrows the class, and `retryable` says whether running the same command again can succeed. `retryable` is `true` for a write-write conflict (exit 5) and for a `--concurrent-logical-workspace-limit` refusal while other statements hold the shared pool (exit 1, kind `resource`; reachable when statements run concurrently, as under `relate serve`). A one-shot CLI run meets only the first. A message's start is enough to find its row: `` marks a part that varies, and `…` marks text left out. ## Find the symptom ### Opening a store | Symptom | Exit code | Reference | What fixes it | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Failed to open Relate: storage locked: ` | [5](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-5) | [`cli-conflict-locked`](https://relatedb.ai/docs/reference/errors/#cli-conflict-locked) | Another process holds the store. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `Error: Failed to open Relate: storage locked: ` when `relate serve` starts | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-conflict-locked`](https://relatedb.ai/docs/reference/errors/#cli-conflict-locked) | The server needs the writer lock. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `storage error: database not found: ` or `storage error: read-only open requires an existing database at ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-storage`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-storage) | A read-only open never creates a store. Check the path. [`--read-only`](https://relatedb.ai/docs/reference/cli/flags/#read-only) | | `storage error: WAL checksum mismatch` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-storage`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-storage) | A damaged WAL; restore a backup. [Recover from a crash](https://relatedb.ai/docs/guides/operate/crash-and-recovery/) | | `storage error: unsupported snapshot version ` or `storage error: unsupported graph value encoding: ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-storage`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-storage) | A newer relate wrote the store. [Upgrade a store](https://relatedb.ai/docs/guides/operate/upgrade-a-store/) | | `semantic error: live freshness (WAL follow) is only supported for native directory databases` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`--read-only`](https://relatedb.ai/docs/reference/cli/flags/#read-only) | Follow a directory store. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `Error: final checkpoint failed: ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-final-checkpoint-failed`](https://relatedb.ai/docs/reference/errors/#cli-final-checkpoint-failed) | Free disk space and check permissions. [Recover from a crash](https://relatedb.ai/docs/guides/operate/crash-and-recovery/) | | An operating-system I/O failure, such as a disk with no space left | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-io`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-io) | Check the path, permissions, and free space. [Choose a store layout](https://relatedb.ai/docs/guides/storage/choose-a-store-layout/) | | Recent writes missing after a crash | — | — | The store ran under a relaxed [durability mode](https://relatedb.ai/docs/reference/glossary/#durability-mode). [Choose a durability mode](https://relatedb.ai/docs/guides/operate/durability-modes/) | ### Memory and size | Symptom | Exit code | Reference | What fixes it | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `capacity exceeded: used=… limit=…` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`engine-graph-size-cap`](https://relatedb.ai/docs/reference/errors/#engine-graph-size-cap), [`cli-fatal-error-capacity`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-capacity) | A write reached `--logical-graph-size-limit`. [Size a store and its memory](https://relatedb.ai/docs/guides/operate/sizing-and-memory/) | | `This statement tried to commit a single WAL record of at least . …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`engine-wal-payload-cap`](https://relatedb.ai/docs/reference/errors/#engine-wal-payload-cap) | Commit in smaller transactions. [Size a store and its memory](https://relatedb.ai/docs/guides/operate/sizing-and-memory/) | | `This statement tried to build a single value of . …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`engine-expression-memory-cap`](https://relatedb.ai/docs/reference/errors/#engine-expression-memory-cap) | Build the value in smaller pieces. [Limits and sizing](https://relatedb.ai/docs/reference/storage/limits-and-sizing/) | | The process ends with no relate error while the graph grows | — | — | The operating system stopped it for memory. [Size a store and its memory](https://relatedb.ai/docs/guides/operate/sizing-and-memory/) | ### Running statements | Symptom | Exit code | Reference | What fixes it | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `syntax error: parse error: …` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`cli-validation-error-syntax`](https://relatedb.ai/docs/reference/errors/#cli-validation-error-syntax) | Fix the statement at the reported column. [Cypher overview](https://relatedb.ai/docs/reference/cypher/overview/) | | `semantic error: ParameterMissing: Expected parameter(s): ` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-parameter-missing`](https://relatedb.ai/docs/reference/errors/#engine-parameter-missing) | Bind each `$name` with `--param`. [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | `semantic error: WriteOnReadOnlyAccessDatabase: …` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-write-on-read-only`](https://relatedb.ai/docs/reference/errors/#engine-write-on-read-only) | Send the write to a writable open. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `syntax error: SafeModeViolation: …` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-safe-mode-violation`](https://relatedb.ai/docs/reference/errors/#engine-safe-mode-violation) | Add the label or the `LIMIT`. [Keep an agent safe](https://relatedb.ai/docs/guides/agents/agent-safety/) | | `semantic error: ConstraintValidationFailed: …` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-constraint-requires-properties`](https://relatedb.ai/docs/reference/errors/#engine-constraint-requires-properties), [`engine-constraint-property-type`](https://relatedb.ai/docs/reference/errors/#engine-constraint-property-type) | Set the constrained property, with a value of the required type, in the same write. [Indexes and constraints](https://relatedb.ai/docs/guides/cypher/indexes-and-constraints/) | | `semantic error: IndexAlreadyExists`, `semantic error: ConstraintAlreadyExists`, `semantic error: ConstraintNotFound` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-index-already-exists`](https://relatedb.ai/docs/reference/errors/#engine-index-already-exists), [`engine-constraint-already-exists`](https://relatedb.ai/docs/reference/errors/#engine-constraint-already-exists), [`engine-constraint-not-found`](https://relatedb.ai/docs/reference/errors/#engine-constraint-not-found) | Add `IF NOT EXISTS` or `IF EXISTS`. [Indexes and constraints](https://relatedb.ai/docs/guides/cypher/indexes-and-constraints/) | | `Unable to drop '': the index belongs to a constraint.`, `semantic error: AlreadyExists: there already exists an index …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) or [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-index-belongs-to-constraint`](https://relatedb.ai/docs/reference/errors/#engine-index-belongs-to-constraint), [`engine-constraint-index-already-exists`](https://relatedb.ai/docs/reference/errors/#engine-constraint-index-already-exists) | Drop the constraint, not its index; drop a plain index before a constraint on the same property. [Indexes and constraints](https://relatedb.ai/docs/guides/cypher/indexes-and-constraints/) | | `type error: VectorIndexDimensionalityMismatch`, `type error: vector() dimension does not match list` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-vector-index-dimensionality-mismatch`](https://relatedb.ai/docs/reference/errors/#engine-vector-index-dimensionality-mismatch), [`engine-vector-dimension-mismatch`](https://relatedb.ai/docs/reference/errors/#engine-vector-dimension-mismatch) | Embed with the model the index was built for. [Vector search](https://relatedb.ai/docs/guides/cypher/vector-search/) | | `syntax error: TraversalDepthExceeded: …` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-traversal-depth-exceeded`](https://relatedb.ai/docs/reference/errors/#engine-traversal-depth-exceeded) | Lower the hop bound or raise `--max-traversal-depth`. [Limits and sizing](https://relatedb.ai/docs/reference/storage/limits-and-sizing/) | | `syntax error: UndefinedVariable: …`, `UnknownFunction: …`, `type error: …`, `ArithmeticError: rounding necessary` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) or [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`engine-undefined-variable`](https://relatedb.ai/docs/reference/errors/#engine-undefined-variable), [`engine-unknown-function`](https://relatedb.ai/docs/reference/errors/#engine-unknown-function), [`cli-validation-error-type`](https://relatedb.ai/docs/reference/errors/#cli-validation-error-type), [`engine-division-by-zero`](https://relatedb.ai/docs/reference/errors/#engine-division-by-zero), [`engine-rounding-necessary`](https://relatedb.ai/docs/reference/errors/#engine-rounding-necessary) | Fix the statement. [Cypher overview](https://relatedb.ai/docs/reference/cypher/overview/) | | `semantic error: NumberOutOfRange` and other rejected argument values | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`cli-validation-error-argument`](https://relatedb.ai/docs/reference/errors/#cli-validation-error-argument) | Correct the value. [Search by vector similarity](https://relatedb.ai/docs/guides/cypher/vector-search/) | | `preview feature '' is not enabled: set RELATE_PREVIEW=` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-preview-feature-not-enabled`](https://relatedb.ai/docs/reference/errors/#engine-preview-feature-not-enabled) | Opt in to the preview feature. [Cypher overview](https://relatedb.ai/docs/reference/cypher/overview/) | | `semantic error: DatabaseNotFound: Graph not found: `, `Unsupported administration command: `, a `USE` or `WITH` refused on an administration command | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-database-not-found`](https://relatedb.ai/docs/reference/errors/#engine-database-not-found), [`engine-unsupported-administration-command`](https://relatedb.ai/docs/reference/errors/#engine-unsupported-administration-command), [`engine-use-on-administration-command`](https://relatedb.ai/docs/reference/errors/#engine-use-on-administration-command), [`engine-with-on-system`](https://relatedb.ai/docs/reference/errors/#engine-with-on-system) | A store has three fixed namespaces. [Differences from Neo4j](https://relatedb.ai/docs/reference/cypher/differences-from-neo4j/) | | A composite-only function, several `USE` targets in one statement | — | [`engine-composite-only-function`](https://relatedb.ai/docs/reference/errors/#engine-composite-only-function), [`engine-multiple-use-targets`](https://relatedb.ai/docs/reference/errors/#engine-multiple-use-targets) | A statement runs against one graph. [Differences from Neo4j](https://relatedb.ai/docs/reference/cypher/differences-from-neo4j/) | | `This database is not queryable. …`, a write to `system_ontologies` | [6](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-6) | [`engine-system-ontologies-not-queryable`](https://relatedb.ai/docs/reference/errors/#engine-system-ontologies-not-queryable), [`engine-system-ontologies-write`](https://relatedb.ai/docs/reference/errors/#engine-system-ontologies-write) | Query the `neo4j` namespace. [Limitations](https://relatedb.ai/docs/reference/limitations/) | | `NestedEvaluationBudgetExceeded: …` | — | [`engine-nested-evaluation-budget`](https://relatedb.ai/docs/reference/errors/#engine-nested-evaluation-budget) | Flatten the nested subqueries. [Limitations](https://relatedb.ai/docs/reference/limitations/) | | `write-write conflict` | [5](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-5) | [`cli-conflict-conflict`](https://relatedb.ai/docs/reference/errors/#cli-conflict-conflict) | Run the statement again in a fresh [transaction](https://relatedb.ai/docs/reference/glossary/#transaction). [Transactions and concurrency](https://relatedb.ai/docs/concepts/transactions-and-concurrency/) | | A uniqueness constraint violated | — | [`engine-uniqueness-violation`](https://relatedb.ai/docs/reference/errors/#engine-uniqueness-violation) | `MERGE` on the constrained key, or fix the duplicate. [Cypher overview](https://relatedb.ai/docs/reference/cypher/overview/) | | `Cannot change the namespace while a transaction is open.` | — | [`engine-namespace-change-in-transaction`](https://relatedb.ai/docs/reference/errors/#engine-namespace-change-in-transaction) | End the transaction first. [Transactions and concurrency](https://relatedb.ai/docs/concepts/transactions-and-concurrency/) | | `Error: query timed out after `, `query cancelled` | [7](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-7) | [`cli-timeout`](https://relatedb.ai/docs/reference/errors/#cli-timeout), [`engine-cancelled`](https://relatedb.ai/docs/reference/errors/#engine-cancelled) | Bound the work or raise the timeout. [Tune a query](https://relatedb.ai/docs/guides/cypher/tune-a-query/) | | A query execution failure while producing rows | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-execution`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-execution) | Read the message; it is not retryable. [Exit codes and errors](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/) | | `internal error` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-fatal-error-internal`](https://relatedb.ai/docs/reference/errors/#cli-fatal-error-internal) | Not the statement's fault. [Collect a report](#collect-a-report) | ### Flags, environment, and input | Symptom | Exit code | Reference | What fixes it | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `Error: unknown flag: `, `Error: unexpected argument: ` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-usage-error`](https://relatedb.ai/docs/reference/errors/#cli-usage-error) | Check the command's flags with `relate --help`. [CLI flags](https://relatedb.ai/docs/reference/cli/flags/) | | `Error: invalid --param value: parameter : …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-invalid-param`](https://relatedb.ai/docs/reference/errors/#cli-invalid-param) | Quote JSON values. [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | `Error: invalid --namespace: …`, `Error: --namespace is not valid with pull …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-invalid-namespace`](https://relatedb.ai/docs/reference/errors/#cli-invalid-namespace), [`cli-pull-namespace`](https://relatedb.ai/docs/reference/errors/#cli-pull-namespace) | Use `neo4j`, `system` or `system_ontologies`, and none with `pull`. [CLI flags](https://relatedb.ai/docs/reference/cli/flags/) | | `Error: invalid --durability-mode: …`, `Error: invalid RELATE_DURABILITY_MODE: …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-invalid-env-durability-mode`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-durability-mode) | Use `full`, `everysecond` or `snapshot`. [Choose a durability mode](https://relatedb.ai/docs/guides/operate/durability-modes/) | | `Error: invalid --logical-graph-size-limit: …`, `Error: invalid RELATE_LOGICAL_GRAPH_SIZE_LIMIT: …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-invalid-env-logical-graph-size-limit`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-logical-graph-size-limit) | Write the size in bytes, `mb`, `mib`, `gb` or `gib`. [Size a store and its memory](https://relatedb.ai/docs/guides/operate/sizing-and-memory/) | | `Error: invalid RELATE_MAX_ROWS: …`, `RELATE_AGENT_MODE`, `RELATE_SAFE_MODE`, `RELATE_EXPRESSION_MEMORY_LIMIT`, `RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT` or `RELATE_MAX_TRAVERSAL_DEPTH` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-invalid-env-max-rows`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-max-rows), [`cli-invalid-env-agent-mode`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-agent-mode), [`cli-invalid-env-safe-mode`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-safe-mode), [`cli-invalid-env-expression-memory-limit`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-expression-memory-limit), [`cli-invalid-env-concurrent-logical-workspace-limit`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-concurrent-logical-workspace-limit), [`cli-invalid-env-max-traversal-depth`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-max-traversal-depth) | Fix or unset the variable. [CLI flags](https://relatedb.ai/docs/reference/cli/flags/) | | `Failed to open Relate: semantic error: SemanticError: invalid RELATE_PREVIEW value: …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-invalid-env-preview`](https://relatedb.ai/docs/reference/errors/#cli-invalid-env-preview) | Use a feature name from the message's list. [CLI flags](https://relatedb.ai/docs/reference/cli/flags/) | | `Error: the '' command is not included in this build of relate` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-command-not-included`](https://relatedb.ai/docs/reference/errors/#cli-command-not-included) | Install a release binary. [Install relate](https://relatedb.ai/docs/get-started/install/) | | `parquet snapshot codec is not compiled into this build …` | — | [`cli-parquet-not-compiled`](https://relatedb.ai/docs/reference/errors/#cli-parquet-not-compiled) | Use the JSON codec or a release binary. [Storage formats](https://relatedb.ai/docs/reference/storage/formats/) | ### Scripts and the shell | Symptom | Exit code | Reference | What fixes it | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `Warning: exiting with an open transaction; rolling back uncommitted changes. …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-open-transaction-at-exit`](https://relatedb.ai/docs/reference/errors/#cli-open-transaction-at-exit) | End the script with `.commit` or `.rollback`. [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | `Error: could not read query input from stdin: ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-stdin-read-error`](https://relatedb.ai/docs/reference/errors/#cli-stdin-read-error) | Pipe valid UTF-8. [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | `note: write statement changed nothing; the graph is unchanged` | [0](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-0) | [`cli-write-changed-nothing`](https://relatedb.ai/docs/reference/errors/#cli-write-changed-nothing) | Not an error: the write matched nothing. [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) | | `warning: result truncated to 100 rows …` | [0](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-0) | [`cli-row-cap-warning`](https://relatedb.ai/docs/reference/errors/#cli-row-cap-warning) | Not an error: `--max-rows 0` prints every row. [Agent mode](https://relatedb.ai/docs/reference/cli/agent-mode/) | | `LOAD CSV file unavailable`, `LOAD CSV file exceeds byte limit` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-load-csv-unavailable`](https://relatedb.ai/docs/reference/errors/#cli-load-csv-unavailable), [`cli-load-csv-byte-limit`](https://relatedb.ai/docs/reference/errors/#cli-load-csv-byte-limit) | Pass `--load-csv-dir` and keep files under 8,388,608 bytes. [Import a CSV](https://relatedb.ai/docs/guides/cypher/import-csv/) | ### Agents and the skill | Symptom | Exit code | Reference | What fixes it | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `Error: skill: refusing to touch : …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-skill-refusing-to-touch`](https://relatedb.ai/docs/reference/errors/#cli-skill-refusing-to-touch) | The folder wasn't written by relate. [Install the agent skill](https://relatedb.ai/docs/guides/agents/install-the-skill/) | | `Error: skill: unknown agent: ''` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-skill-unknown-agent`](https://relatedb.ai/docs/reference/errors/#cli-skill-unknown-agent) | Use a name from the `valid agents:` line. [Install the agent skill](https://relatedb.ai/docs/guides/agents/install-the-skill/) | | `Only MATCH queries are allowed for read-query`, `Only write queries are allowed for write-query` | — | [`mcp-read-query-only`](https://relatedb.ai/docs/reference/errors/#mcp-read-query-only), [`mcp-write-query-only`](https://relatedb.ai/docs/reference/errors/#mcp-write-query-only) | The statement went to the other MCP tool. [Connect over MCP](https://relatedb.ai/docs/guides/agents/connect-over-mcp/) | | `malformed JSON-RPC message: `, `unsupported JSON-RPC version ''`, an unknown method or bad parameters, `Error: internal error` | — | [`mcp-parse-error`](https://relatedb.ai/docs/reference/errors/#mcp-parse-error), [`mcp-unsupported-version`](https://relatedb.ai/docs/reference/errors/#mcp-unsupported-version), [`mcp-method-not-found`](https://relatedb.ai/docs/reference/errors/#mcp-method-not-found), [`mcp-invalid-params`](https://relatedb.ai/docs/reference/errors/#mcp-invalid-params), [`mcp-internal-error`](https://relatedb.ai/docs/reference/errors/#mcp-internal-error) | The MCP host and server disagree. [Connect over MCP](https://relatedb.ai/docs/guides/agents/connect-over-mcp/) | ### Serving over HTTP, MCP and Bolt | Symptom | Exit code | Reference | What fixes it | | ------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP `401 Unauthorized`, or `The client is unauthorized due to authentication failure.` over Bolt | — | [`http-unauthorized`](https://relatedb.ai/docs/reference/errors/#http-unauthorized), [`bolt-unauthorized`](https://relatedb.ai/docs/reference/errors/#bolt-unauthorized) | Send the server's password for the user `relate`. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `transaction expired after s idle`, `transaction registry full: …` | — | [`http-transaction-expired`](https://relatedb.ai/docs/reference/errors/#http-transaction-expired), [`http-transaction-registry-full`](https://relatedb.ai/docs/reference/errors/#http-transaction-registry-full) | Commit sooner, or raise the server's limits. [relate CLI](https://relatedb.ai/docs/reference/cli/) | | `query result exceeds max-result-bytes limit of bytes` | — | [`bolt-result-too-large`](https://relatedb.ai/docs/reference/errors/#bolt-result-too-large) | Return fewer or smaller rows. [Tune a query](https://relatedb.ai/docs/guides/cypher/tune-a-query/) | | HTTP 400, 404 or 500, a malformed Bolt message | — | [`http-malformed-or-syntax`](https://relatedb.ai/docs/reference/errors/#http-malformed-or-syntax), [`http-not-found`](https://relatedb.ai/docs/reference/errors/#http-not-found), [`http-general`](https://relatedb.ai/docs/reference/errors/#http-general), [`http-internal`](https://relatedb.ai/docs/reference/errors/#http-internal), [`bolt-request-invalid`](https://relatedb.ai/docs/reference/errors/#bolt-request-invalid) | Read the error in the response body. [Errors](https://relatedb.ai/docs/reference/errors/) | | MCP over HTTP answers `415`, `{"error":"the request content type is browser-\"simple\" …"}` | — | [`mcp-http-unsupported-media-type`](https://relatedb.ai/docs/reference/errors/#mcp-http-unsupported-media-type) | Send `Content-Type: application/json`. [Serve a store over MCP](https://relatedb.ai/docs/guides/serve/mcp/) | | MCP over HTTP answers `401`, `{"error":"authentication required"}` | — | [`mcp-http-unauthorized`](https://relatedb.ai/docs/reference/errors/#mcp-http-unauthorized) | Send `Authorization: Basic` with the server's credential. [Serve a store over MCP](https://relatedb.ai/docs/guides/serve/mcp/) | | MCP over HTTP answers `403`, `{"error":"origin is not allowed"}`, or `405` | — | [`mcp-http-origin-forbidden`](https://relatedb.ai/docs/reference/errors/#mcp-http-origin-forbidden), [`mcp-http-method-not-allowed`](https://relatedb.ai/docs/reference/errors/#mcp-http-method-not-allowed) | Send `POST` requests without a browser `Origin`, or from a loopback one. [MCP server](https://relatedb.ai/docs/reference/server/mcp/#errors-and-refusals) | ### Starting relate serve | Symptom | Exit code | Reference | What fixes it | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Error: serve has nothing to serve: …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-serve-nothing-to-serve`](https://relatedb.ai/docs/reference/errors/#cli-serve-nothing-to-serve) | Pass `--http PORT`, `--mcp PORT\|stdio` or `--bolt PORT`. [relate serve](https://relatedb.ai/docs/reference/cli/serve/#errors-and-exit-codes) | | `Error: serve -- : cannot bind :: ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-serve-bind-failed`](https://relatedb.ai/docs/reference/errors/#cli-serve-bind-failed) | Choose a free port, or stop the process that holds it. [Serve a store over MCP](https://relatedb.ai/docs/guides/serve/mcp/) | | `Error: Failed to open Relate: ` from `relate serve` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-serve-open-failed`](https://relatedb.ai/docs/reference/errors/#cli-serve-open-failed) | Stop the other opener, or serve a directory store `--read-only` beside its writer. [Share one store between two processes](https://relatedb.ai/docs/guides/operate/two-processes-one-store/) | | `Error: serve takes --read-only after the verb, not before it …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-serve-read-only-before-verb`](https://relatedb.ai/docs/reference/errors/#cli-serve-read-only-before-verb) | Put `--read-only` after `serve`. [relate serve](https://relatedb.ai/docs/reference/cli/serve/#read-only-serving) | | `Error: --auth: expected user:password or 'none'`, `Error: RELATE_AUTH: …`, `Error: --auth requires USER:PASSWORD or none` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) or [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-serve-auth-malformed`](https://relatedb.ai/docs/reference/errors/#cli-serve-auth-malformed), [`cli-serve-env-auth-malformed`](https://relatedb.ai/docs/reference/errors/#cli-serve-env-auth-malformed), [`cli-serve-env-auth-empty-side`](https://relatedb.ai/docs/reference/errors/#cli-serve-env-auth-empty-side), [`cli-serve-auth-missing-value`](https://relatedb.ai/docs/reference/errors/#cli-serve-auth-missing-value) | Pass `:` or `none`. [Authentication and TLS](https://relatedb.ai/docs/guides/serve/auth-and-tls/) | | `Error: serve --mcp stdio skips auth …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-serve-auth-stdio`](https://relatedb.ai/docs/reference/errors/#cli-serve-auth-stdio) | Drop `--auth` from a stdio-only command. [Connect over MCP](https://relatedb.ai/docs/guides/agents/connect-over-mcp/) | ### Copying stores and Neo4j | Symptom | Exit code | Reference | What fixes it | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Failed to clone database: storage locked: ` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-clone-locked`](https://relatedb.ai/docs/reference/errors/#cli-clone-locked) | Wait for the writer to exit, or clone a directory store. [Clone and convert a store](https://relatedb.ai/docs/guides/storage/clone-and-convert/) | | `Failed to clone database: storage error: database not found: `, `… wal_dir is not supported for .rl single-file databases …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-clone-source-missing-rl`](https://relatedb.ai/docs/reference/errors/#cli-clone-source-missing-rl), [`cli-clone-wal-dir-rl`](https://relatedb.ai/docs/reference/errors/#cli-clone-wal-dir-rl) | Correct `SOURCE`; drop `--wal-dir` for a `.rl` source. [relate clone](https://relatedb.ai/docs/reference/cli/clone/#what-clone-refuses) | | `Failed to clone database: semantic error: markdown body properties are set …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-clone-markdown-body-properties-codec`](https://relatedb.ai/docs/reference/errors/#cli-clone-markdown-body-properties-codec) | Add `--to-snapshot-format markdown`, or drop `--markdown-body-properties`. [Clone and convert a store](https://relatedb.ai/docs/guides/storage/clone-and-convert/) | | `Error: destination database is not empty; pull writes into an empty database only …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-pull-destination-not-empty`](https://relatedb.ai/docs/reference/errors/#cli-pull-destination-not-empty) | Pull into a new path. [Pull a subgraph from Neo4j](https://relatedb.ai/docs/guides/neo4j/pull-from-neo4j/) | | `Error: missing from environment`, `Error: missing from env file` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-pull-credential-missing`](https://relatedb.ai/docs/reference/errors/#cli-pull-credential-missing), [`cli-pull-env-file-key`](https://relatedb.ai/docs/reference/errors/#cli-pull-env-file-key) | Set `NEO4J_URI`, `NEO4J_USERNAME` and `NEO4J_PASSWORD`. [Pull a subgraph from Neo4j](https://relatedb.ai/docs/guides/neo4j/pull-from-neo4j/) | | `Error: refusing to send Basic auth credentials in the clear: …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) | [`cli-pull-plaintext`](https://relatedb.ai/docs/reference/errors/#cli-pull-plaintext) | Use an `https://` `NEO4J_URI`. [relate pull](https://relatedb.ai/docs/reference/cli/pull/) | | `Error: shape query RETURN must be graph elements …`, `Error: pull cannot target :memory: …` | [1](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-1) or [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-pull-shape-query`](https://relatedb.ai/docs/reference/errors/#cli-pull-shape-query), [`cli-pull-memory`](https://relatedb.ai/docs/reference/errors/#cli-pull-memory) | Return nodes, relationships or paths; name a directory or `.rl` path. [Pull a subgraph from Neo4j](https://relatedb.ai/docs/guides/neo4j/pull-from-neo4j/) | | `Error: push takes one of --query, --labels, or --types …`, `Error: --merge-key "" must be NAME:PROP[,PROP] …`, `Error: --namespace is not valid with push …` | [2](https://relatedb.ai/docs/reference/cli/exit-codes-and-errors/#exit-2) | [`cli-push-one-scope`](https://relatedb.ai/docs/reference/errors/#cli-push-one-scope), [`cli-push-merge-key-format`](https://relatedb.ai/docs/reference/errors/#cli-push-merge-key-format), [`cli-push-namespace`](https://relatedb.ai/docs/reference/errors/#cli-push-namespace) | Pass one selector and `