> ## Documentation Index
> Fetch the complete documentation index at: https://nativeharness.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error carries a code. The codes, by layer, and what each one asks you to do.

Everything the harness throws is an `Error` with a `code`. Branch on the code, not the
message — messages are for humans and will change. Three families:

## Store — `StoreError`

| Code                   | Meaning                                                                                                     | Do                                             |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `not_found`            | no such workspace, session, file or execution                                                               | a bad id from your side                        |
| `conflict`             | an export target already exists; a duplicate idempotency key                                                | pick another path, or read the existing result |
| `invalid_path`         | not a workspace path, or a traversal                                                                        | a bug in the caller                            |
| `invalid_state`        | the operation does not fit the record's state — resuming a turn that is not suspended, exporting mid-commit | check the state first                          |
| `limit`                | a size cap                                                                                                  | the workspace's limits, or split the write     |
| `format` / `integrity` | an import that is not a workspace, or fails its checksum                                                    | do not import it                               |
| `unsupported`          | this store does not do that                                                                                 | a different store                              |

## Sandbox — `SandboxError`

| Code                    | Meaning                                                        | Do                                                                |
| ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------- |
| `unavailable`           | no engine at the socket                                        | `nhar doctor`; on rootless Podman, check `loginctl enable-linger` |
| `image`                 | the image could not be pulled                                  | check the reference and the registry                              |
| `gone`                  | the sandbox is not there any more — reaped, or removed         | acquire again; the workspace is intact                            |
| `exec`                  | the engine could not run the command                           | the message carries the engine's words                            |
| `timeout` / `cancelled` | as named — a `BashResult` normally carries these, not an error |                                                                   |
| `limit`                 | the provider refused a resource limit                          | lower it, or fix cgroup delegation on the host                    |
| `internal`              | a provider bug                                                 | report it                                                         |

## Harness — `HarnessError`

Raised above the providers, most often `forbidden`: the session's actor is not in the
workspace's permissions, or a `discard` actor asked for a `commit` session.

## A command that fails is not an error

`bash.execute` resolves with a `BashResult` whose `exit_code` is non-zero — a red test suite is
an outcome your code decides about, not something that goes down the `catch` path. The
result's `error` field, when set, is a `BashErrorCode`: `timeout`, `sandbox`, `hydrate`,
`sync`, `scope` or `internal`, naming which stage went wrong.

## In the event stream

A failure during a turn is also an `error` event — `{ code: "model" | "sandbox" | "store" |
"connector" | "internal", message, recoverable }` — so the UI can show it where it happened,
and `done` reports the turn as `failed`.