Troubleshooting

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 holds the complete entry for each one.

Prerequisites

• The error's text from stderr and the command's exit codeexit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary.
• relate on your PATH (Install relate).
• To follow along, the shared example graph as team.rl:

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 storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary's name is misspelled, tema.rl, so a read-only open finds nothing to open:

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 <dir>. The first line is stderr, the second the error objecterror object The JSON object a failed query run prints on stdout in the json, jsonl, envelope and speedscope modes: the class, the kind, the message, the exit code. Read more in the glossary on stdout:

Failed to open Relate: storage error: database not found: <dir>/tema.rl
{"error":{"code":"fatal_error","exit_code":1,"kind":"storage","message":"storage error: database not found: <dir>/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: <name> marks a part that varies, and … marks text left out.

Find the symptom

Opening a store

Memory and size

Running statements

Flags, environment, and input

Scripts and the shell

Agents and the skill

Serving over HTTP, MCP and Bolt

Starting relate serve

Copying stores and Neo4j

Extensions

Client libraries and the browser

These errors come from a client library, not the CLI, so they have no exit code.

Client library errors lists every client message, including the exception classes of each language.

Collect a report

When a row says to report, or no row fits, these four things let someone else reproduce the problem without your data:

The version check prints two lines:

relate --version

Relate v0.1.2
License: Apache 2.0 (binary)

Verify

After the fix, the command that failed exits 0. With the store's name spelled right:

relate --database ./team.rl --read-only --mode envelope "MATCH (p:Person) RETURN count(p) AS people"
echo "exit=$?"

{"columnTypes":["INTEGER"],"columns":["people"],"notifications":[],"planCache":"miss","rows":[{"people":3}],"timings":{"elapsed_ms":0.339834,"execute_ms":0.17541700000000002,"lex_parse_ms":0.028416999999999998,"lower_ms":0.041665999999999995,"parse_ms":0.102959,"plan_ms":0.052375,"result_generation_ms":0.00033299999999999996,"rewrite_ms":0.008291999999999999},"truncated":false}
exit=0

If it goes wrong

• The message is in no table. Search the errors reference for its first words; it lists every error with its cause and remedy.
• The exit code is 3, 4, or 8. relate reserves those codes and doesn't produce them. Check which program in the pipeline returned it (exit codes).
• internal error. An engine invariant failed, which is not the statement's fault. Collect a report with the statement that caused it.

Related

• Errors: every error, its cause, remedy, and exit code.
• Exit codes and errors: the exit code table and the error object's fields.
• Recover from a crash and Share one store between two processes: the two storage guides this page links most.