Error reference

Every LoraDB error carries a stable LORA_* code drawn from a single catalog. The code is part of the public API and never changes between releases; the human-readable message is allowed to evolve. Bindings, the HTTP server, and integration tests should match on the code, never on the message.

Codes

Client errors (caller's fault)

Code	When you'll see it
LORA_PARSE	Cypher syntax could not be parsed, or the query is past a shape limit (nesting, operator chain, clause count, hop count).
LORA_SEMANTIC	Unknown variable or function, wrong arity, or type mismatch.
LORA_INVALID_PARAMS	A parameter value couldn't be coerced into a Lora value, or is nested or sized past the value limits.
LORA_READ_ONLY	A mutating statement was issued in a read-only context.
LORA_NOT_FOUND	A named entity (database, label, key) does not exist.
LORA_CONSTRAINT	A precondition failed (e.g. DELETE on a node with relationships — use DETACH DELETE).
LORA_VALIDATION	A well-formed database operation failed validation, including a value a query builds or stores past the value limits.
LORA_UNIQUE_CONSTRAINT	A uniqueness constraint rejected duplicate data.
LORA_NOT_NULL_CONSTRAINT	An existence / NOT NULL constraint rejected missing data.
LORA_FOREIGN_KEY	A relationship or dependent record references a missing entity.
LORA_TRANSACTION	A transaction lifecycle rule was violated.
LORA_LOCKED	The database directory is locked by another process or live handle.
LORA_CHANGES_TRUNCATED	A change feed was asked to resume from an LSN the database no longer retains. Start a fresh feed and re-read current state.
LORA_CHANGES_LAGGED	A change feed subscriber fell further behind than its buffer allows. Resume with the last LSN it processed.
LORA_INVALID_VECTOR	A vector value failed dimension or coordinate-type validation.
LORA_TIMEOUT	The query exceeded its cooperative deadline.
LORA_RESULT_TOO_LARGE	HTTP server only. The query's result has more rows than --max-result-rows, or its response is larger than --max-response-bytes. Add a LIMIT or page with SKIP / LIMIT.
LORA_DATABASE_NAME	A logical database name violates the portable-path rules.
LORA_CONFIG	A CLI flag or configuration value is invalid.

Server errors (engine's fault)

Code	When you'll see it
LORA_IO	An I/O failure outside the WAL / snapshot subsystems.
LORA_CONNECTION	The database backing connection or handle failed.
LORA_WAL_CORRUPTION	A WAL record was truncated, mis-CRC'd, or otherwise unreadable.
LORA_WAL_POISONED	The WAL is poisoned and no longer accepts durable writes.
LORA_SNAPSHOT_CODEC	Snapshot bad magic, version, or checksum.
LORA_SNAPSHOT_CRYPTO	Snapshot encryption / decryption / KDF failure.
LORA_INTERNAL	The engine could not classify the failure.

Binding-side codes

Code	When you'll see it
LORA_PANIC	A Rust panic was caught at a binding boundary. The process keeps running; the call returns this code instead.
LORA_TOO_MANY_OPEN	Node only. The database already has maxOpenTransactions interactive transactions and write streams open (1024 by default). Finish or close one, or raise the limit. Read-write transaction() batches queue instead.

HTTP transport

The Axum server returns errors as JSON:

{
  "error": {
    "code": "LORA_PARSE",
    "message": "parse error at 0..10: expected statement",
    "category": "client"
  }
}

category is "client" (4xx) or "server" (5xx). The HTTP status code follows the category, with these refinements:

Status	Codes
400 Bad Request	LORA_PARSE, LORA_SEMANTIC, LORA_READ_ONLY, LORA_DATABASE_NAME, LORA_CONFIG
404 Not Found	LORA_NOT_FOUND
408 Request Timeout	LORA_TIMEOUT
409 Conflict	LORA_CONSTRAINT, LORA_UNIQUE_CONSTRAINT, LORA_NOT_NULL_CONSTRAINT, LORA_FOREIGN_KEY, LORA_TRANSACTION
422 Unprocessable Entity	LORA_INVALID_PARAMS, LORA_INVALID_VECTOR, LORA_VALIDATION, LORA_RESULT_TOO_LARGE
500 Internal Server Error	LORA_IO, LORA_WAL_CORRUPTION, LORA_SNAPSHOT_CODEC, LORA_SNAPSHOT_CRYPTO, LORA_INTERNAL
503 Service Unavailable	LORA_CONNECTION, LORA_WAL_POISONED

Examples per language

Rust

use lora_database::{Database, LoraError, LoraErrorCode};

let db = Database::in_memory();
match db.execute("NOT CYPHER", None) {
    Ok(_) => {}
    Err(e) => {
        let lora = LoraError::from_anyhow(e);
        if lora.code() == LoraErrorCode::Parse {
            eprintln!("syntax: {}", lora.message());
        }
    }
}

Node.js / TypeScript

import { LoraError } from "@loradb/lora-node";

try {
  await db.execute("NOT CYPHER");
} catch (err) {
  if (err instanceof LoraError) {
    if (err.code === "LORA_PARSE") console.error("syntax:", err.message);
  }
}

err.code is the precise wire string from the catalog above, for example "LORA_PARSE" or "LORA_INVALID_PARAMS".

Python

from lora_python import LoraQueryError

try:
    db.execute("NOT CYPHER")
except LoraQueryError as e:
    code, _, message = str(e).partition(": ")
    if code == "LORA_PARSE":
        print(f"syntax: {message}")

Go

import (
    "errors"
    "fmt"

    lora "github.com/lora-db/lora/crates/bindings/lora-go"
)

if _, err := db.Execute("NOT CYPHER", nil); err != nil {
    var le *lora.LoraError
    if errors.As(err, &le) && le.Code == lora.CodeParse {
        fmt.Println("syntax:", le.Message)
    }
}

Ruby

begin
  db.execute("NOT CYPHER")
rescue LoraRuby::QueryError => e
  code, _, message = e.message.partition(": ")
  warn "syntax: #{message}" if code == "LORA_PARSE"
end

WASM / browsers

try {
  await db.execute("NOT CYPHER", null);
} catch (err) {
  if (err.code === "LORA_PARSE") console.warn("syntax", err.message);
}

Why match on codes, not messages

Codes are the contract. Messages are advisory: between minor releases we rewrite individual #[error("...")] strings to make them clearer or include more context. Anything matching message text — if err.message.contains("not found") — will silently break. Match on LORA_NOT_FOUND instead.