Error codes

Every failure in Strata carries a code. Not a message you match on, and not a number you look up in a table somewhere: a stable identifier that says what kind of failure it was, whether retrying is safe, and whether your write took effect.

That last part is the unusual one. Most error registries tell you what went wrong. This one also tells you what happened to your data, which is the question you actually need answered before you decide what to do next.

What a code looks like

Codes read left to right, from the kind of problem to the specific case:

conflict.engine.promotion
│        │      └ the specific failure
│        └ the component that raised it
└ the class, one of 16

Match on the code, or on its class prefix if you want to handle a whole family at once. Do not match on the message: messages are written for people and are free to change, while codes are the contract.

The two fields worth branching on

Every entry in the registry carries both, and between them they decide what you do next.

retry_policy

never · 186 codes

Retrying the same request will fail the same way. Something has to change first, usually your input.

after_state_change · 20 codes

Retry once the condition has changed: reload the current state, or wait for the resource to exist.

unknown · 9 codes

Strata cannot say. Treat it as unsafe to retry blindly and reconcile first.

same_request · 7 codes

The identical request is worth retrying, typically after a backoff.

commit_outcome

not_started · 132 codes

The command was rejected before it touched anything. Nothing was written.

not_applicable · 84 codes

The command does not write, so there is nothing to have committed.

definitely_not_committed · 4 codes

The command started and did not commit. Nothing was written.

maybe_committed · 2 codes

Strata does not know whether the write landed. Check before acting.

A caller that reads these two fields can recover automatically without guessing. A conflict on a merge says never and not_started: your target branch is untouched, and repeating the identical request will fail identically, so reload and decide. A closed runtime says after_state_change: the same call will work once the runtime is open again.

When Strata does not know

2 of the 222 codes report maybe_committed. They are worth knowing by name, because they are the only ones where reading the error is not enough:

• ambiguous_commit.engine.persistence

  Re-open or inspect database state before assuming whether the write committed.

• unavailable.executor.ipc_transport

  Reopen the database (the owner may have exited or restarted) and, for a write, confirm whether it applied before retrying.

Both are transport and persistence failures where the write may have landed before the answer was lost. There is an error class named ambiguous_commit for exactly this, which is a deliberate choice: a system that cannot tell you should say so rather than guess. Read the record back before retrying, or make the write idempotent so that retrying is harmless either way.

Finding a code

The full registry is at the error index, grouped by class, with a page per code carrying its message, hint, retry policy and commit outcome. Every code links there directly, so https://stratadb.org/e/<code> resolves for any of the 222 of them, and the binary prints that URL in the error itself.

125 of them are declared by a command in the catalog, so each command page lists the codes it can raise alongside their retry policy and commit outcome. The rest come from the runtime and the storage layer beneath the command surface.

The same registry is available offline, matched to the version you installed:

strata agents errors --json