--- title: Errors description: "relate, the embedded Cypher graph database (relatedb.ai): The errors relate reports, each at a stable anchor, with its message where it is recorded, its cause, remedy, whether a retry helps, and the CLI exit code." type: reference surfaces: - cli - cypher - http - bolt - mcp - python - agents status: stable verified: 0.1.2 verified_by: - cli canonical_url: https://relatedb.ai/docs/reference/errors/ prerequisites: [] related: - get-started/agent-quickstart - reference/cli/exit-codes-and-errors - guides/operate/troubleshooting last_updated: 2026-11-08 --- # Errors The errors relate reports, each at a stable anchor, with its message where it is recorded, its cause, remedy, whether a retry helps, and the CLI exit code. > Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2 Each error relate reports has a stable id, and each id is an anchor on this page: `https://relatedb.ai/docs/reference/errors/#`. A row gives the message pattern as relate prints it, where it is recorded, the cause, the remedy, whether retrying the same statement can succeed, and the CLI exit code. The tables are generated from one data file, so this page and its markdown twin list the same entries. ## Synopsis On the CLI, a failed statement prints its message on stderr and exits with the [exit code](https://relatedb.ai/docs/reference/glossary/#exit-code) of its class. In `--mode envelope`, `--json` and `--jsonl`, it also prints an [error object](https://relatedb.ai/docs/reference/glossary/#error-object) on stdout. The object's `code` is the class, `kind` is the engine's error variant, `retryable` is `true` for a write-write conflict and for a `--concurrent-logical-workspace-limit` refusal while other statements hold the workspace pool, and `message` repeats the stderr text. ```bash verify relate --mode envelope 'RETURN $x AS x' ``` The first line of the output is stderr, the second is stdout: ```text semantic error: ParameterMissing: Expected parameter(s): x {"error":{"code":"validation_error","exit_code":6,"kind":"semantic","message":"semantic error: ParameterMissing: Expected parameter(s): x","retryable":false}} ``` A syntax error adds `column` and `source`, so a caller can point at the failing token without parsing the message: ```text syntax error: parse error: expected RightParen, got "RETURN" (RETURN) MATCH (n RETURN n ^ {"error":{"code":"validation_error","column":10,"exit_code":6,"kind":"syntax","message":"syntax error: parse error: expected RightParen, got \"RETURN\" (RETURN) MATCH (n RETURN n ^","retryable":false,"source":"MATCH (n RETURN n"}} ``` `relate agent-context` prints the exit codes of the installed version: ```text Exit codes: 0 success: success, including an empty result 1 fatal_error: runtime failure: store open or I/O error, capacity limit, query execution failure, internal error 2 usage_error: unknown flag, bad or missing value, extra positional 5 conflict: write-write conflict, or the store is locked by another opener 6 validation_error: the statement is rejected: syntax, semantic or type error 7 timeout: a statement exceeded --timeout ``` In the tables, a message's `` marks a variable part and `…` is an elision in the source. A dash (—) means the sources do not state the value, or it does not apply to that [surface](https://relatedb.ai/docs/reference/glossary/#surface). ## CLI errors Errors and notices from the `relate` command itself: statement classes, flag and environment checks, and the skill installer. | Error | Message | Cause | Remedy | Retryable | Exit code | | --- | --- | --- | --- | --- | --- | | `cli-validation-error-syntax`; code `validation_error`, kind `syntax`; Neo4j `Neo.ClientError.Statement.SyntaxError`; HTTP 400; Python `ProgrammingError` | `syntax error: parse error: unexpected token ""` | The statement does not parse. The error object adds `column` and `source` when the parser reports a position. Another recorded form: `syntax error: parse error: expected RightParen, got "RETURN" (RETURN)`. The stderr form adds the source line and a caret under the column. | Fix the statement at the reported column; a did-you-mean line follows when the first word is close to a command name. | no | 6 | | `cli-validation-error-semantic`; code `validation_error`, kind `semantic`; Neo4j `Neo.ClientError.Statement.SemanticError`; Python `OperationalError` | `semantic error: ` | The statement parses but is rejected before it runs: a missing parameter, an unknown namespace, a write on a read-only open, and similar. | Read the detail after `semantic error:`; the typed engine errors (ParameterMissing, DatabaseNotFound and others) have their own entries. | no | 6 | | `cli-validation-error-argument`; code `validation_error`, kind `argument`; Neo4j `Neo.ClientError.General.InvalidArguments`; Python `DataError` | — | An argument value is rejected, for example a DDL `OPTIONS`/`indexConfig` value. Recorded form: `semantic error: NumberOutOfRange` for a negative vector dimension; the prefix is `semantic error:` although the kind is `argument`. On Bolt the same rejection arrives at RUN as FAILURE `Neo.ClientError.General.InvalidArguments` with message `semantic error: NumberOutOfRange`. | Correct the rejected value. | no | 6 | | `cli-validation-error-type`; code `validation_error`, kind `type`; GQL status `22G03`; Neo4j `Neo.ClientError.Statement.TypeError`; HTTP 400; Python `DataError` | `type error: ` | A value has the wrong type for the operation. | Convert or check the value's type in the statement. | no | 6 | | `cli-fatal-error-execution`; code `fatal_error`, kind `execution` | — | A query execution failure discovered while producing rows. | Read the message; execution failures are not retryable. | no | 1 | | `cli-conflict-conflict`; code `conflict`, kind `conflict`; Neo4j `Neo.TransientError.Transaction.Outdated` | `write-write conflict` | Two transactions wrote the same data; the later one lost. The Java, Go and Swift clients report the conflict from `commit()` with code `Neo.TransientError.Transaction.Outdated`, GQL status `42000`, stage runtime, retryable true (Java `TransientException`). | Re-run the statement in a fresh transaction. One of the two retryable errors; the other is a contended workspace-pool refusal. | yes | 5 | | `cli-conflict-locked`; code `conflict`, kind `locked`; Neo4j `Neo.DatabaseError.General.UnknownError` | `storage locked: ` | Another process holds the store: a persistent store takes exclusive ownership of its directory and WAL, or its `.rl` file, at open. The error object's `message` is `storage locked: `; stderr prints `Failed to open Relate: storage locked: `. A `--read-only` open of a `.rl` file is refused the same way while a writer holds it. For a directory store, `` is the writer lock file inside it. `relate serve` on a store another process holds stops at startup with `Error: Failed to open Relate: storage locked: ` and exit code 1, not 5 ([cli-serve-open-failed](https://relatedb.ai/docs/reference/errors/#cli-serve-open-failed)); `relate clone` of a held `.rl` source exits 1 too ([cli-clone-locked](https://relatedb.ai/docs/reference/errors/#cli-clone-locked)). | Close the other opener, or open with `--read-only` (a directory store can be read beside its writer; a `.rl` file only while no writer holds it). Not retryable until the other opener exits. | no | 5 | | `cli-clone-locked` | `Failed to clone database: storage locked: ` | `relate clone` with a `.rl` source while another process holds it open for writing; no error object is printed. | Wait for the writer to exit, or clone a directory store, which can be cloned while its writer runs. | — | 1 | | `cli-serve-open-failed` | `Error: Failed to open Relate: ` | `relate serve` could not open its store: another process holds it (`storage locked: `), or a `--read-only` open names a store that does not exist. It stops at startup; no error object is printed. The query run reports the same lock with exit code 5 ([cli-conflict-locked](https://relatedb.ai/docs/reference/errors/#cli-conflict-locked)); `relate serve` exits 1. | Stop the other opener, or serve a directory store `--read-only` beside its writer; check the `--database` path. | — | 1 | | `cli-fatal-error-capacity`; code `fatal_error`, kind `capacity`; Neo4j `Neo.ClientError.General.TransactionOutOfMemoryError`; HTTP 507; Python `DataError` | `capacity exceeded: used=… limit=…` | A memory or capacity limit refused the work: the `--logical-graph-size-limit` cap, the per-allocation expression cap, or the 64 MiB per-record WAL payload cap. | Raise the named limit, or commit the data in smaller transactions. | no | 1 | | `cli-fatal-error-resource`; code `fatal_error`, kind `resource` | `resource limit exceeded: concurrent-logical-workspace-limit limit=` | The statement needs more shared workspace than `--concurrent-logical-workspace-limit` allows. | Retry when fewer statements run, or raise `--concurrent-logical-workspace-limit`. | no | 1 | | `cli-fatal-error-storage`; code `fatal_error`, kind `storage`; Neo4j `Neo.DatabaseError.General.UnknownError` | `storage error: ` | A storage failure, for example a corrupt snapshot or an unsupported stored value encoding at open. Recorded forms: `storage error: database not found: ` (a missing `.rl`), `storage error: read-only open requires an existing database at ` (a missing or empty directory), `storage error: read-only open requires an existing WAL at /wal` (a directory store without its WAL folder), `storage error: snapshot codec mismatch: directory is , requested ` (`--snapshot-format` against an existing store), `storage error: wal_dir is not supported for .rl single-file databases …` (`--wal-dir` with a `.rl` store; nothing is created), and `storage error: unsupported snapshot version ` (a store written by a newer relate; `relate info` prints `Failed to read store info: storage error: unsupported snapshot version `). Also seen: `storage error: WAL checksum mismatch` (a damaged WAL record before the tail; `--read-only` and `relate clone` fail the same way, clone prefixed `Failed to clone database: `) and `storage error: unsupported graph value encoding: ` (JSON). stderr prefixes `Failed to open Relate: `. | Restore from a backup clone; do not copy a snapshot without its WAL. | no | 1 | | `cli-unsupported-uri-scheme`; code `fatal_error`, kind `storage`; Python `OperationalError` | `storage error: unsupported URI scheme :// (engine URIs are :memory:, a filesystem path, or file://)` | `--database` was given a URL such as `bolt://` or `neo4j://`; a store is a path or `:memory:`. stderr prefixes `Failed to open Relate: `. | Open a path, or serve the store with `relate serve --bolt --database --read-only`. | no | 1 | | `cli-live-freshness-unsupported`; code `fatal_error`, kind `semantic` | `semantic error: live freshness (WAL follow) is only supported for native directory databases` | `--read-only=live` on a `.rl` store or `:memory:`; only a directory store has a WAL to follow. stderr prefixes `Failed to open Relate: `. | Use `--read-only` (a snapshot at open), or a directory store. | no | 1 | | `cli-fatal-error-io`; code `fatal_error`, kind `io`; Neo4j `Neo.DatabaseError.General.UnknownError` | — | An operating-system I/O failure, including a full disk. | Check the path, permissions and free space. | no | 1 | | `cli-fatal-error-internal`; code `fatal_error`, kind `internal`; GQL status `50N42`; Neo4j `Neo.DatabaseError.General.UnknownError`; HTTP 500; Python `InternalError` | `internal error` | An engine invariant failed; not the statement's fault. | Report it with `relate --version` and the statement. | no | 1 | | `cli-timeout`; code `timeout`, kind `execution` | `Error: query timed out after ` | A statement ran longer than `--timeout`. stderr prints `Error: query timed out after `; the error object's `message` drops the `Error: ` prefix. `--timeout 0.1` prints as `100ms`. | Bound the work with `LIMIT` or a narrower pattern, or raise `--timeout`. | no | 7 | | `cli-usage-error`; code `usage_error` | `Error: unknown flag: ` | A parser usage error: unknown flag, bad or missing value, extra positional. stderr carries the `Error:` line, the command's `Usage:` line and a `--help` hint; a close match adds `Did you mean ''?`. An extra positional prints `Error: unexpected argument: `. | Run `relate --help`. | — | 2 | | `cli-command-not-included`; code `usage_error` | `Error: the '' command is not included in this build of relate` | The command's feature is not compiled into this build bundle (release binaries are the full bundle). | Use a full build. | — | 2 | | `cli-invalid-param`; code `usage_error` | `Error: invalid --param value: parameter : …` | A `--param` value that looks like JSON does not parse, is a non-finite number, or is an integer above i64::MAX. | Quote JSON values; JSON-quote a date that starts with digits. | — | 2 | | `cli-fetch-params-failed` | `Error: --fetch-params : ` | A `--fetch-params` source could not be read or fetched, is over the 64 MiB cap, or is not JSON; nothing runs, and no error object is printed. Recorded forms: `Error: --fetch-params : invalid JSON: ` and `Error: --fetch-params : reading : ` (for example `No such file or directory (os error 2)`, or `source exceeded the 64 MiB cap`). A value without `=` is a usage error instead: `Error: invalid --fetch-params value: expected name=value`, exit code 2. An HTTP source that answers an error status prints `Error: --fetch-params : HTTP ` (observed as HTTP 404). | Check the path or URL and that the source is one JSON document. | — | 1 | | `cli-invalid-namespace`; code `usage_error` | `Error: invalid --namespace: unknown namespace '' (expected neo4j, system or system_ontologies)` | `--namespace` names something other than the three fixed namespaces. | Use `neo4j`, `system` or `system_ontologies`. | — | 2 | | `cli-pull-namespace`; code `usage_error` | `Error: --namespace is not valid with pull (pull always writes the neo4j namespace)` | `--namespace` placed before the `pull` verb. | Drop `--namespace`; pull always writes `neo4j`. | — | 2 | | `cli-invalid-env-max-rows`; code `usage_error` | `Error: invalid RELATE_MAX_ROWS: '' is not a non-negative integer` | `RELATE_MAX_ROWS` is not a non-negative integer. | Set an integer; `0` is unlimited. | — | 2 | | `cli-invalid-env-agent-mode`; code `usage_error` | `Error: invalid RELATE_AGENT_MODE: '' is neither 1 nor 0` | `RELATE_AGENT_MODE` is not `1` or `0`. | Set `1` or `0`, or unset it. | — | 2 | | `cli-invalid-env-durability-mode`; code `usage_error` | `Error: invalid RELATE_DURABILITY_MODE: semantic error: invalid durability mode ""; expected full, everysecond, or snapshot` | `RELATE_DURABILITY_MODE` is not `full`, `everysecond` or `snapshot`. | Use one of the three values. | — | 2 | | `cli-invalid-env-safe-mode`; code `usage_error` | `Error: invalid RELATE_SAFE_MODE: '' is not 1 or 0` | `RELATE_SAFE_MODE` is not `1` or `0`. | Set `1` or `0`, or unset it. | — | 2 | | `cli-safe-remote-load`; code `usage_error` | `Error: --safe refuses a remote --load source — a downloaded store is untrusted input, so safe mode introduces none …` | `--safe` (or `RELATE_SAFE_MODE=1`) with an `https://` `--load` source, on the query run or on `relate serve`; refused before any network request. The binary ends the message with an upstream reference in parentheses. | Download the file, check its SHA-256, and pass the local path to `--load`; or drop `--safe`. | — | 2 | | `cli-load-plain-http`; code `usage_error` | `Error: invalid --load: plain http:// is only allowed for a loopback host; use https://` | A `--load` URL uses plain `http://` for a host other than a loopback address. | Use the `https://` URL the message names, or a local file. | — | 2 | | `cli-invalid-env-logical-graph-size-limit`; code `usage_error` | `Error: invalid RELATE_LOGICAL_GRAPH_SIZE_LIMIT: semantic error: invalid memory limit ''` | The value does not parse as a size. | Use bytes or mb/mib/gb/gib; `0` is unlimited. | — | 2 | | `cli-invalid-env-expression-memory-limit`; code `usage_error` | `Error: invalid RELATE_EXPRESSION_MEMORY_LIMIT: invalid memory limit ''` | The value does not parse as a size. | Use a size, or `none`. | — | 2 | | `cli-invalid-env-concurrent-logical-workspace-limit`; code `usage_error` | `Error: invalid RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT: must be positive` | The variable is `0`; a value that does not parse prints `Error: invalid RELATE_CONCURRENT_LOGICAL_WORKSPACE_LIMIT: invalid memory limit ''` instead. | Use a positive size, or unset it to leave admission off. | — | 2 | | `cli-invalid-env-max-traversal-depth`; code `usage_error` | `Error: invalid RELATE_MAX_TRAVERSAL_DEPTH: must be between 1 and 2000` | `0` or a value over 2000; a non-integer prints `Error: invalid RELATE_MAX_TRAVERSAL_DEPTH: '' is not a number` instead. | Use an integer from 1 to 2000. | — | 2 | | `cli-invalid-env-preview`; code `fatal_error`, kind `semantic` | `Failed to open Relate: semantic error: SemanticError: invalid RELATE_PREVIEW value: unknown preview feature '' (known features: …)` | `RELATE_PREVIEW` names a feature the engine does not know; the open fails closed. The error object's `message` drops the `Failed to open Relate: ` prefix. | Use a name from the known-features list in the message. | — | 1 | | `cli-invalid-env-pattern-engine`; code `fatal_error`, kind `semantic` | `semantic error: invalid RELATE_PATTERN_ENGINE: semantic error: invalid pattern engine ""; expected auto, nfa, or walk` | `RELATE_PATTERN_ENGINE` is not `auto`, `nfa` or `walk`; the open fails. stderr prefixes `Failed to open Relate: `. | Use one of the three values, or unset it. | no | 1 | | `cli-invalid-env-bulk-batch-threshold`; code `fatal_error`, kind `semantic` | `semantic error: invalid RELATE_BULK_BATCH_THRESHOLD ''` | `RELATE_BULK_BATCH_THRESHOLD` is not a number; the open fails. stderr prefixes `Failed to open Relate: `. | Set a whole number, or unset it. | no | 1 | | `cli-invalid-env-snapshot-format`; code `fatal_error`, kind `storage` | `storage error: unknown snapshot codec '' (expected parquet, json, markdown or rkyv)` | `RELATE_SNAPSHOT_FORMAT` names no codec the variable takes (`parquet-wide` is a flag value only); a query run's open fails, `:memory:` included. stderr prefixes `Failed to open Relate: `. The same value given as `--snapshot-format` is a usage error, exit code 2: `Error: invalid --snapshot-format: storage error: unknown snapshot format '' (expected parquet or json or markdown or parquet-wide)`. `rkyv` is not compiled into the release binary: `RELATE_SNAPSHOT_FORMAT=rkyv` fails the open with `storage error: rkyv snapshot codec is not compiled into this build (enable the "rkyv-codec" feature)`. | Use `parquet`, `json` or `markdown`, or unset it; for wide-column parquet, pass `--snapshot-format parquet-wide`. | no | 1 | | `cli-final-checkpoint-failed`; code `fatal_error` | `Error: final checkpoint failed: ` | The checkpoint every persistent run takes on exit failed, for example on a full disk. A non-zero statement exit code is kept instead. | Free disk space and check permissions. | — | 1 | | `cli-open-transaction-at-exit` | `Warning: exiting with an open transaction; rolling back uncommitted changes. Use .commit before exiting to persist them.` | A `.begin` transaction was still open at exit. One-shot and piped runs exit 1; the interactive shell keeps exit 0. | End the script with `.commit` (or `.rollback`). | — | 1 | | `cli-stdin-read-error` | `Error: could not read query input from stdin: ` | Piped stdin could not be read, including invalid UTF-8; nothing runs. | Pipe valid UTF-8. | — | 1 | | `cli-load-csv-unavailable`; code `fatal_error`, kind `execution` | `LOAD CSV file unavailable` | A `LOAD CSV` path escapes the configured root, is a symlink escape or a special file, does not exist, or local files are denied (no `--load-csv-dir`). | Pass `--load-csv-dir ` and keep files under it. | no | 1 | | `cli-load-csv-byte-limit`; code `fatal_error`, kind `execution` | `LOAD CSV file exceeds byte limit` | The CSV file is over 8,388,608 bytes. | Split the file; the limit cannot be raised from the CLI. | no | 1 | | `cli-load-csv-invalid-configuration`; code `fatal_error`, kind `semantic` | `semantic error: LOAD CSV invalid configuration` | The directory given to `--load-csv-dir` (or `RELATE_LOAD_CSV_DIR`) does not exist or is not a directory; the open fails. stderr prefixes `Failed to open Relate: `. | Create the directory first, or correct the path. | no | 1 | | `cli-parquet-not-compiled` | `parquet snapshot codec is not compiled into this build (enable the "parquet" feature)` | `--snapshot-format parquet` in a build without the parquet feature. | Use `--snapshot-format json`, or a full build. | — | — | | `cli-skill-refusing-to-touch` | `Error: skill: refusing to touch : no .relate-installed marker present (directory was not created by relate); pass --force to override` | The skills destination exists and was not written by relate. | Move the directory, or pass `--force` to overwrite it. | — | 1 | | `cli-skill-unknown-agent` | `Error: skill: unknown agent: ''` | `--agent` names an agent the CLI does not know; a second line lists the valid agents. | Use a name from the `valid agents:` line. | — | 2 | | `cli-skill-no-agents` | `Error: skill: no supported agents detected` | A `relate skill` action ran without `--agent` and none of the agents' configuration directories exists in the home directory; a second line lists the valid agents. | Pass `--agent ` with a name from the `valid agents:` line. | — | 1 | | `cli-row-cap-warning`; severity warning | `warning: result truncated to 100 rows (the statement returned 250); pass --max-rows 0 for all rows` | Not an error. The row cap cut the printed rows (100 by default under a detected agent harness with stdout not a terminal). The counts in the message vary. | Pass `--max-rows 0` for all rows, or bound the work with `LIMIT`. | — | 0 | | `cli-write-changed-nothing`; severity notice | `note: write statement changed nothing; the graph is unchanged` | Not an error. A write statement applied nothing, often because a zero-row `MATCH` short-circuited it. In a script the note names the statement (`note: write statement 2 of 3 changed nothing; …`), and a transaction that persisted nothing prints `note: .commit changed nothing; the transaction applied no changes`. | Grep stderr for the prefix `note: write statement`; the exit code stays 0. | — | 0 | | `cli-serve-nothing-to-serve`; code `usage_error` | `Error: serve has nothing to serve: pass --http PORT and/or --mcp PORT\|stdio and/or --bolt PORT` | `relate serve` with no listener flag; ports have no defaults. | Pass at least one of `--http PORT`, `--mcp PORT\|stdio` or `--bolt PORT`. | — | 2 | | `cli-serve-read-only-before-verb`; code `usage_error` | `Error: serve takes --read-only after the verb, not before it (relate serve --read-only …)` | `--read-only` placed before the `serve` word. | Put `--read-only` after `serve`. | — | 2 | | `cli-serve-auth-malformed` | `Error: --auth: expected user:password or 'none'` | `--auth` has no colon. | Pass `:` or `none`. | — | 1 | | `cli-serve-env-auth-malformed` | `Error: RELATE_AUTH: expected user:password or 'none'` | `RELATE_AUTH` has no colon. | Set `RELATE_AUTH` to `:` or `none`. | — | 1 | | `cli-serve-env-auth-empty-side` | `Error: RELATE_AUTH: expected user:password with both sides non-empty` | `RELATE_AUTH` has an empty user or password. | Set both sides of `RELATE_AUTH`. | — | 1 | | `cli-serve-auth-missing-value`; code `usage_error` | `Error: --auth requires USER:PASSWORD or none` | `--auth` is the last argument, with no value. | Pass `--auth :` or `--auth none`. | — | 2 | | `cli-serve-auth-stdio`; code `usage_error` | `Error: serve --mcp stdio skips auth (the host spawned the process, ADR-0232); --auth applies to the --http PORT/--mcp PORT/--bolt listeners only` | `--auth` with `--mcp stdio` as the only listener; the stdio transport has no credential. | Drop `--auth`, or add an HTTP, MCP-over-HTTP or Bolt listener for it to guard. | — | 2 | | `cli-serve-bind-failed` | `Error: serve -- : cannot bind :: ` | Another process listens on the port, or the address is not available on this machine. On macOS the reason reads `Address already in use (os error 48)`; the OS error number differs by platform. | Choose a free port, or stop the process that holds it. | — | 1 | | `cli-open-readonly-missing-dir` | `Failed to open Relate: storage error: read-only open requires an existing database at ` | `--read-only` on a directory path that holds no store; a read-only open never creates one. | Correct the path, or create the store with a writable open first. | — | 1 | | `cli-open-readonly-missing-rl` | `Failed to open Relate: storage error: database not found: ` | `--read-only` on a `.rl` path that does not exist; a read-only open never creates one. | Correct the path, or create the store with a writable open first. | — | 1 | | `cli-clone-wal-dir-rl` | `Failed to clone database: storage error: wal_dir is not supported for .rl single-file databases (ADR-0074)` | `relate clone --wal-dir` with a `.rl` source, which holds its own WAL. | Drop `--wal-dir`; it applies to a directory source only. | — | 1 | | `cli-clone-markdown-body-properties-codec` | `Failed to clone database: semantic error: markdown body properties are set but the store's snapshot codec is parquet, not markdown; the configuration would be ignored` | `--markdown-body-properties` on a clone whose destination codec is not `markdown`. | Add `--to-snapshot-format markdown`, or drop `--markdown-body-properties`. | — | 1 | | `cli-clone-source-missing-rl` | `Failed to clone database: storage error: database not found: ` | The `.rl` SOURCE does not exist. | Correct the SOURCE path. | — | 1 | | `cli-info-not-found` | `Failed to read store info: storage error: database not found: ` | `relate info --database` names a path with no store. | Correct the path. | — | 1 | | `cli-telemetry-no-config-dir` | `Error: telemetry: cannot resolve a config directory (set $XDG_CONFIG_HOME, $HOME, $APPDATA, or $USERPROFILE)` | `relate telemetry on` or `off` with no config directory base: no absolute `XDG_CONFIG_HOME`, no `HOME`, and no absolute `APPDATA` or `USERPROFILE`, so there is nowhere to write its config file. A failed write prints `Error: telemetry: writing : ` (from the source; not reproduced). | Set `HOME`, or set `XDG_CONFIG_HOME` to an absolute path; `DO_NOT_TRACK=1` turns usage metrics off without a config directory. | — | 1 | | `cli-pull-destination-not-empty` | `Error: destination database is not empty; pull writes into an empty database only (ADR-0158)` | `relate pull` into a store that already holds data. The check runs before any connection. | Pull into a new path; a pull never merges. | — | 1 | | `cli-pull-shape-query` | `Error: shape query RETURN must be graph elements (nodes/rels/paths), not projections/scalars/aggregates; rejected item: ` | A `--query` statement returns a property, a scalar or an aggregate; pull copies only nodes, relationships and paths. | Return the graph elements themselves, such as `RETURN n`. | — | 1 | | `cli-pull-plaintext` | `Error: refusing to send Basic auth credentials in the clear: Query API URL is http:// to a non-loopback host; pass --allow-plaintext to accept the risk, or use an https:// NEO4J_URI` | The Neo4j URI resolves to `http://` on a host other than the loopback interface, so the credentials would cross the network unencrypted. | Use an `https://` `NEO4J_URI`, or pass `--allow-plaintext` to accept the risk. | — | 1 | | `cli-pull-memory`; code `usage_error` | `Error: pull cannot target :memory: (--database must persist)` | `relate pull --database :memory:`; the copy would vanish when the command exits. | Name a directory or `.rl` path. | — | 2 | | `cli-pull-credential-missing` | `Error: missing from environment` | No `--from` env file, and a Neo4j variable the pull needs is not set. | Set `NEO4J_URI`, `NEO4J_USERNAME` and `NEO4J_PASSWORD`, or name an env file with `--from`. | — | 1 | | `cli-pull-env-file-key` | `Error: missing from env file` | The `--from` env file lacks one of `NEO4J_URI`, `NEO4J_USERNAME` or `NEO4J_PASSWORD`. No store is created. | Add the key to the env file. | — | 1 | | `cli-query-no-statements` | `Error: no statements in --query value` | `relate pull` or `relate push` got a `--query` value with no statement in it. | Pass at least one statement. | — | 1 | | `cli-push-one-scope`; code `usage_error` | `Error: push takes one of --query, --labels, or --types (none pushes the whole store)` | More than one of `--query`, `--labels` and `--types`. | Pass one selector, or none to push the whole store. | — | 2 | | `cli-push-namespace`; code `usage_error` | `Error: --namespace is not valid with push (push always reads the neo4j namespace)` | `--namespace` with `relate push`. | Drop `--namespace`. | — | 2 | | `cli-push-merge-key-format`; code `usage_error` | `Error: --merge-key "" must be NAME:PROP[,PROP] (no ':' found)` | A `--merge-key` value without a colon. | Pass `