# dwarves error codes — `dwarves-<subsystem>-<n>`
**GENERATED — do not edit by hand.** This file is produced from `dwarves::errcode::REGISTRY` (`crates/dwarves/src/errcode.rs`), the single source of truth, by `registry_document()`. The test `errcode::tests::the_committed_registry_doc_matches_the_compiled_registry` fails if this file and the code disagree, so the catalog and the doc cannot drift.
**56 codes** across 11 subsystems — **41 wired**, **15 reserved**.
## The scheme
Every NON-UI error site in dwarves carries a stable, unique code `dwarves-<subsystem>-<n>`, so tests and consumers react to the CODE rather than to a matched substring of a human message. It is the dwarves half of the suite-wide scheme: facett owns the UI codes (`facet-<component>-<n>`), korp owns `korp-<subsystem>-<n>`.
* **Frozen + append-only.** An `<n>` is assigned ONCE per subsystem and never renumbered or reused. A retired code keeps its row. A new site takes the next free integer.
* **Unique.** No code repeats globally; no `<n>` repeats within a subsystem. Guarded by `errcode::tests::codes_are_globally_unique_and_per_subsystem_n_unique`.
* **Dual channels.** A raised error always carries BOTH the unchanged human string and the code. The code lands in `state_json` (`error_code` / `error`), in logs (`log_line()` → `dwarves-proxy-2: …`), and in any gRPC `Status` (message + the `x-dwarves-code` metadata header). `Display` is `"<message> [<code>]"`, so a code survives being flattened into an `anyhow` chain or a bare `Err(String)`.
* **Consumer mount-prefix.** A consumer that mounts dwarves twice prepends its own prefix — `njord/ci:dwarves-forge-3` — leaving the base code untouched.
## wired vs reserved
* **wired** — the code is RAISED at a real error site in its listed source file today.
* **reserved** — the number is claimed, frozen and unique, but the site is not coded yet. The source column names where it is earmarked.
This distinction is **guarded**, in both directions, by `errcode::tests::every_wired_code_is_actually_raised_in_its_declared_file`: a `wired` row whose file does not raise it FAILS the build, and a `reserved` row that IS raised somewhere fails too. A registry that merely lists codes will happily claim coverage it does not have — that false-green is exactly what this guard retires.
### `buildthing` — 12 code(s) (10 wired, 2 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `buildthing` | `dwarves-buildthing-1` | no checkouts — the constellation root is missing or declares no build space | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-2` | repo is checked out but declares no build space (.nornir/build-variants.toml absent) | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-3` | build-variants.toml could not be parsed | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-4` | declared build set does not validate — a shape rule, an on-disk input, or a consumption edge's typ | `crates/dwarves/src/buildthing.rs` | wired |
| `buildthing` | `dwarves-buildthing-5` | cargo build FAILED — the compiler reported errors or a non-zero exit | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-6` | cargo exited 0 but produced NO artifact — this is not a success | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-7` | the build could not be started (worker/spawn setup failed) | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-8` | egress audit NOT MEASURED — cargo tree could not resolve the dependency closure | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-9` | no such build variant in the selected repo's declared set | `crates/dwarves/src/build_thing.rs` | reserved |
| `buildthing` | `dwarves-buildthing-10` | the build filed NO warehouse record — build_provenance/build_info received zero rows | `crates/dwarves/src/build_thing.rs` | wired |
| `buildthing` | `dwarves-buildthing-11` | the build-record store could not be READ (unreachable / auth / not served) — this is NOT an empty store | `dwarves-gui/src/build_forge.rs` | reserved |
| `buildthing` | `dwarves-buildthing-12` | the forge's recipe READER is older than the recipe — rebuild/reinstall dwarves | `crates/dwarves/src/build_thing.rs` | wired |
### `launch` — 8 code(s) (6 wired, 2 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `launch` | `dwarves-launch-1` | no launch cell is armed — select a cell before Run/Boot | `dwarves-gui/src/build_forge.rs` | reserved |
| `launch` | `dwarves-launch-2` | the container run could not be started | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-3` | container-run is not enabled in this build — rebuild with --features container-run | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-4` | vm-boot is not enabled in this build — rebuild with --features vm-boot | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-5` | the boot/run ended FAILED — it never reached its BOOT-OK/ready marker | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-6` | the boot/run was cancelled — a kill is never a passed gate | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-7` | no real appliance is wired for this launch cell | `dwarves-gui/src/boot_run.rs` | wired |
| `launch` | `dwarves-launch-8` | this ISO cell is a live-boot scaffold — it cannot boot a kernel yet | `dwarves-gui/src/boot_run.rs` | reserved |
### `proxy` — 3 code(s) (3 wired, 0 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `proxy` | `dwarves-proxy-1` | warehouse-proxy: the embedded-nornir url is malformed | `crates/dwarves/src/warehouse_proxy.rs` | wired |
| `proxy` | `dwarves-proxy-2` | warehouse-proxy: the embedded nornir is UNREACHABLE (dead upstream) | `crates/dwarves/src/warehouse_proxy.rs` | wired |
| `proxy` | `dwarves-proxy-3` | warehouse-proxy: the upstream answered with an error status | `crates/dwarves/src/warehouse_proxy.rs` | wired |
### `warehouse` — 4 code(s) (1 wired, 3 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `warehouse` | `dwarves-warehouse-1` | warehouse UNAVAILABLE — the read could not reach a server | `dwarves-gui/src/mimir_lens.rs` | wired |
| `warehouse` | `dwarves-warehouse-2` | the warehouse has no such table | `dwarves-gui/src/mimir_lens.rs` | reserved |
| `warehouse` | `dwarves-warehouse-3` | the workspace is not registered in the warehouse | `dwarves-gui/src/warehouse_select.rs` | reserved |
| `warehouse` | `dwarves-warehouse-4` | the warehouse answered with rows that do not match the requested schema | `dwarves-gui/src/mimir_lens.rs` | reserved |
### `mimir` — 3 code(s) (2 wired, 1 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `mimir` | `dwarves-mimir-1` | the Mímir lens fold is UNAVAILABLE — the upstream did not answer | `dwarves-gui/src/mimir_lens.rs` | wired |
| `mimir` | `dwarves-mimir-2` | a Mímir lens RPC returned a body that is not valid lens JSON | `crates/nornir-warehouse-embed/src/mimir.rs` | reserved |
| `mimir` | `dwarves-mimir-3` | a remote lens source has no local warehouse to fold | `dwarves-gui/src/mimir_lens.rs` | wired |
### `forge` — 11 code(s) (10 wired, 1 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `forge` | `dwarves-forge-1` | no pipeline descriptor was found for this repo | `crates/dwarves/src/brokkr/descriptor.rs` | reserved |
| `forge` | `dwarves-forge-2` | the pipeline descriptor could not be parsed | `crates/dwarves/src/brokkr/descriptor.rs` | wired |
| `forge` | `dwarves-forge-3` | a pipeline step FAILED (non-zero exit) | `crates/dwarves/src/runner.rs` | wired |
| `forge` | `dwarves-forge-4` | no runner is available for this step kind | `crates/dwarves/src/runner.rs` | wired |
| `forge` | `dwarves-forge-5` | the repo source could not be fetched/checked out | `crates/dwarves/src/repo.rs` | wired |
| `forge` | `dwarves-forge-6` | the repo needs a deploy key, but none was found | `crates/dwarves/src/repo.rs` | wired |
| `forge` | `dwarves-forge-7` | a variant's tests could not be RUN (the step never got a verdict) | `crates/dwarves/src/runner.rs` | wired |
| `forge` | `dwarves-forge-8` | a step named a variant cargo cannot build (kernel/container/iso/installer) | `crates/dwarves/src/runner.rs` | wired |
| `forge` | `dwarves-forge-9` | an assembled packaging cell produced NO artifact (the medium/image the step named is not there) | `crates/dwarves/src/runner.rs` | wired |
| `forge` | `dwarves-forge-10` | the remote repository does NOT EXIST — deregister it from the forge or fix the url | `crates/dwarves/src/repo.rs` | wired |
| `forge` | `dwarves-forge-11` | the remote repository is EMPTY — no HEAD advertised; it waits for a first push | `crates/dwarves/src/repo.rs` | wired |
### `node` — 2 code(s) (0 wired, 2 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `node` | `dwarves-node-1` | the embedded nornir node failed to start | `crates/dwarves/src/bin/dwarves-server.rs` | reserved |
| `node` | `dwarves-node-2` | the embedded nornir node's port is already in use | `crates/dwarves/src/bin/dwarves-server.rs` | reserved |
### `vault` — 7 code(s) (7 wired, 0 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `vault` | `dwarves-vault-1` | the vault is LOCKED — unlock it before reading secrets | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-2` | vault unlock failed — wrong passphrase or corrupt vault | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-3` | no secret by that name in the vault | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-4` | not a dwarves vault (bad magic or truncated file) | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-5` | refusing a non-SSH git url — the vault drives git over SSH ONLY (LAW) | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-6` | the vault passphrase is not valid UTF-8 — the shared key provider takes text | `crates/dwarves/src/vault.rs` | wired |
| `vault` | `dwarves-vault-7` | the vault is still in the pre-absorption DWVAULT1 format — unlock once with the passphrase to migrate it | `crates/dwarves/src/vault.rs` | wired |
### `mcp` — 4 code(s) (1 wired, 3 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `mcp` | `dwarves-mcp-1` | this MCP verb needs NORNIR_SERVER (and a workspace) to be set | `crates/dwarves/src/agent_bridge.rs` | reserved |
| `mcp` | `dwarves-mcp-2` | the funnel intake (submit idea) failed | `crates/dwarves/src/funnel_action.rs` | reserved |
| `mcp` | `dwarves-mcp-3` | the funnel decompose failed (grounding or the Claude call) | `crates/dwarves/src/funnel_action.rs` | wired |
| `mcp` | `dwarves-mcp-4` | the autonom repo scan failed | `crates/dwarves/src/agent_bridge.rs` | reserved |
### `funnel` — 1 code(s) (0 wired, 1 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `funnel` | `dwarves-funnel-1` | the funnel server could not be reached | `crates/dwarves/src/funnel_action.rs` | reserved |
### `docs` — 1 code(s) (1 wired, 0 reserved)
| subsystem | code | visible message | source | status |
|---|---|---|---|---|
| `docs` | `dwarves-docs-1` | dwarves docs needs the doc-book engine — rebuild with --features docs | `crates/dwarves/src/main.rs` | wired |