Every StrataDB failure carries a stable code. Read the code, not the prose, and these situations resolve quickly.

Start with strata doctor

strata doctor is the first diagnostic. With no argument it checks the installation; give it a database path and it also tries to open it and reports what it finds. It exits non-zero when something needs attention, so it is safe to script.

A healthy run reports path_ok: true and an empty issues array. When a database will not open, doctor says so and names the code (output abbreviated):

strata ./mydb doctor

{
  "database": {
    "exists": true,
    "open_ok": false,
    "path": "./mydb"
  },
  "issues": [
    {
      "code": "unavailable.engine.persistence",
      "hint": "Retry after the local persistence layer is available."
    }
  ],
  "path_ok": true,
  "platform": "linux-x86_64"
}

How to read an error

Failures print a <class>.<area>.<detail> code, a one-line hint, and a reference URL:

not_found.engine.branch: source branch `nonesuch` does not exist (err_local_37433bfb_000001)
  hint: Check that the requested branch, space, collection, graph, document, key, or model exists.
  ref: https://stratadb.org/e/not_found.engine.branch

The class (the first segment) tells you how to react: not_found, invalid_argument, and already_exists mean fix the request; failed_precondition means the database is in a state that blocks the operation; unavailable means retry after the underlying layer recovers; corruption means stop and inspect. Open the ref URL — the same /e/<code> page — for the details, or look any code up offline with strata agents errors --json. Add --json to any command to get the same information as a structured envelope. Recover by code, never by message text.

command not found after install

If your shell prints strata: command not found, the binary is installed but not on your PATH for this shell. Open a new terminal (the installer edits your shell profile), or follow the PATH steps in Installation. strata doctor reports path_ok once the binary is reachable.

No database specified

error: [invalid_argument.cli.no_database]: no database specified
  hint: pass a path (strata ./mydb kv put …), set STRATA_DB, or use --cache for ephemeral

StrataDB never opens the current directory implicitly. Pass a path (strata ./mydb …), set STRATA_DB, or use --cache for an ephemeral database. This is the invalid_argument.cli.no_database code — CLI usage errors like it print a plain error: line, exit with status 2, and are not in the /e/ registry, so look them up by reading the printed hint.

The database will not open

A path that is not a directory, a directory the process cannot read or write, or a database whose files were altered underneath it all surface as unavailable.engine.persistence:

unavailable.engine.persistence: persistence lower layer is unavailable (err_local_010d5985_000001)
  hint: Retry after the local persistence layer is available.
  ref: https://stratadb.org/e/unavailable.engine.persistence

Check that the path points at a database directory you own and can write, that no other process is holding it, and that the disk is not full. strata <path> doctor confirms whether the open succeeds — the path is a global argument, so it comes before the subcommand. Treat a database directory as one unit — do not edit or remove files inside it by hand.

Opening a pre-V1 database

Databases created before the V1 line are rejected on open with failed_precondition.engine.layout_version, class failed_precondition. From the registry, its message is “The database layout is incompatible with this runtime,” and its hint is to open the database with a compatible version. This line does not migrate pre-V1 development databases — create a fresh database and reload your data. Look the code up with strata agents errors --json.

Durability and recovery failures

If the storage layer cannot make a write durable, the writer stops rather than report a false success, and operations surface in the unavailable class (unavailable.engine.persistence and related codes) with a retry-after-recovery hint. Recovery is explicit: fix the underlying condition — free space, permissions, a healthy disk — and reopen the database.

If stored data fails validation while recovering, you get corruption.engine.persistence_recovery, whose hint is blunt: “Stop writing to the database and inspect recovery diagnostics before continuing.” Do exactly that — take a copy of the directory and inspect it before any further writes.

Getting more help

• FAQ — what changed in this line and why.
• Error reference — every code with its class and meaning.
• Observability guide — health and metrics surfaces beyond doctor.