# Error codes

Every framework failure is an `UltimateError` carrying a stable `X_*` code, a concrete cause, and the exact command or edit that fixes it. Same content in the terminal, the dev overlay, the HTTP body, the MCP tool result and `--json`.

```text
X_DB_DRIFT: schema differs from migrations
  cause: table "posts" has column "publish_at" not present in any migration
  fix:   x db gen "add publish_at"
```

```json
{"code":"X_DB_DRIFT","title":"schema differs from migrations","cause":"table \"posts\" has column \"publish_at\" not present in any migration","fix":"x db gen \"add publish_at\"","docs":"https://github.com/developerz-ai/ultimate/wiki/Error-Codes"}
```

The HTTP body is the same content as an RFC 9457 problem document — `type`, `title`, `status`, `detail`, plus `code`, `cause`, `fix`, `docs`, `requestId` and `retry` (`terminal`, `retryable` or `retry-after`: the class a client maps to an exception, on every document, a hidden 5xx included) as top-level extension members. Two more are carried when the error has them: `issues`, the per-field rejections of a validation failure, and `meta`, the keys of the error's own `meta` that the app declared for that code with `registerProblemMeta` (everything else in `meta` is operator-only and never leaves the process). Both are all-or-nothing and both are dropped, with `cause`, on a 5xx nobody classified.

| Rule | Detail |
|---|---|
| Lookup | `x errors explain <CODE> --json`, or the MCP `errors.explain` tool — same content as this page |
| Uniqueness | one code is owned by exactly one package; a collision throws `X_ERROR_CODE_DUPLICATE` at registration |
| Stability | codes never change meaning. A renamed concept gets a new code and the old one stays documented |
| `fix` | always runnable or editable as written. If a fix reads "do the right thing", that is a bug — [file it](https://github.com/developerz-ai/ultimate/issues) |
| Bare `Error` | never thrown by the framework. Anything caught is normalised through `toUltimateError()` |
| Registration | a code exists when its owning package calls `registerErrorCodes()`. That one call is what makes it explainable, unique and documented-or-fail — a code emitted as a `Finding` rather than thrown is registered the same way |
| App codes | an app declares each of its own codes ONCE: `defineError({ code, title, status, cause, fix })` from `@ultimat3/core` (`offSocket: true` in place of `status` for a code no response carries) registers the title, the HTTP status and the retry, and returns the class to throw — `throw new PostNotFound(ref)`, `PostNotFound.is(error)`. A code with no status answers 500 and hides its cause, so the call makes you choose. An app code needs no row on this page; `guards/error-declared.ts` refuses a handwritten `UltimateError` subclass and a literal-coded `new UltimateError`. A framework code goes through `bun run new-error-code` instead |
| Enforcement | the `errors` step of `x verify` fails on an empty or advice-only `fix` (`X_ERROR_FIX_INVALID`), on a `fix` citing a file the repo does not have (`X_ERROR_FIX_PATH_MISSING`), on a declared code with no row on this page (`X_ERROR_CODE_UNDOCUMENTED`), on a row this page presents as live that no package registers (`X_ERROR_CODE_UNREGISTERED`), and on a `code:` reached through a name nothing in its own file declares (`X_ERROR_CODE_UNRESOLVED`) |

`As of 2026-10` every code above [Reserved codes](#reserved-codes) resolves through `x errors explain`, with one exception the gate knows about: this repository's own gate scripts (`X_BOUNDARY_VIOLATION`, `X_ROADMAP_*`, `X_REFERENCE_APP_*`, `X_TRUST_*`, `X_CATALOG_CARRIER_UNSCANNED`, `X_CATCH_RENDER_PIN_STALE`, `X_CATCH_RENDER_UNSAFE`, `X_CATCH_RENDER_UNSCANNED`, `X_CONFIG_KEY_UNREAD`, `X_CONFIG_READERS_UNSCANNED`, `X_CONFIG_READER_PIN_STALE`, `X_DECLARED_KEY_UNREAD`, `X_DECLARATION_READER_PIN_STALE`, `X_DECLARATION_READERS_UNSCANNED`, `X_DOC_COMMAND_PIN_EXCEEDED`, `X_DOC_CONFIG_KEY_UNKNOWN`, `X_DOC_CONFIG_ALLOWANCE_STALE`, `X_SCAFFOLD_VERIFY_UNREADABLE`, `X_TIER_FLOOR_STALE`, `X_TIER_FLOOR_UNDECLARED`, `X_SCAFFOLD_OVERRIDES_EMPTY`, `X_SCAFFOLD_GATE_RED`, `X_SCAFFOLD_FIRST_RUN_FAILED`, `X_SETUP_INSTALL_FAILED`, `X_ADMIN_FLATTENER_VIOLATION`, `X_CONFIG_IMPORT_OUTSIDE_LOADER`, `X_ERROR_RENDER_UNSAFE`, `X_ERROR_STATUS_MISSING`, `X_ERROR_STATUS_BACKLOG_STALE`, `X_ERROR_STATUS_UNKNOWN_CODE`, `X_CATALOG_KEY_UNREACHABLE`, `X_PUBLISH_LIST_INCOMPLETE`, `X_PUBLISH_LIST_UNKNOWN`, `X_BENCH_CLAIM_STALE`, `X_BENCH_URL_REQUIRED`, `X_BENCH_STREAM_CLOSED`, `X_BENCH_RUN_TOO_SHORT`, `X_BENCH_RUN_FAILED`, `X_WIKI_TABLE_MALFORMED`, `X_WIKI_TABLE_UNSCANNED`, `X_FRAME_DOCS_STALE`, `X_CHART_VERSION_STALE`, `X_IMAGE_LIBC_MISMATCH`, `X_IMAGE_GUARD_MISSING`, `X_IMAGE_SECRET_UNIGNORED`, `X_IMAGE_CONTENT_UNIGNORED`, `X_DOC_FIX_UNRUNNABLE`, `X_DOC_FIX_UNSCANNED`, `X_DOC_FIX_DISAGREES`, `X_DOC_FIX_DISAGREES_PIN_STALE`, `X_DOC_CAUSE_ECHOES_TITLE`, `X_DOC_COMMAND_UNKNOWN`, `X_DOC_COMMAND_ALLOWANCE_STALE`, `X_DOC_COMMAND_UNSCANNED`, `X_DOC_COMMAND_PIN_STALE`, `X_DOC_TEST_PATH_BARE`, `X_DOC_TEST_PATH_UNSCANNED`, `X_TSCONFIG_PATH_MISSING`, `X_TSCONFIG_PATH_STALE`, `X_TSCONFIG_PATHS_UNSCANNED`, `X_DOC_GATE_STEPS_STALE`, `X_DOC_GATE_STEPS_UNSCANNED`, `X_DOC_SETUP_COMMAND_STALE`, `X_DOC_SETUP_COMMANDS_UNSCANNED`, `X_DOC_SETUP_COMMAND_STALE`, `X_DOC_SETUP_COMMANDS_UNSCANNED`, `X_README_EXAMPLE_UNCOMPILED`, `X_README_EXAMPLE_PIN_STALE`, `X_README_EXAMPLE_UNSCANNED`, `X_README_SAMPLE_DRIFT`, `X_README_FACTS_DRIFT`, `X_PRODUCTION_APPS_DRIFT`, `X_ADOPTION_CLAIM_UNGENERATED`, `X_PACKAGE_README_SHAPE`, `X_PACKAGE_KEYWORDS_MISSING`, `X_VERSION_STAMP_STALE`, `X_VERSION_STAMP_DUPLICATE`, `X_VERSION_LOCKSTEP_BROKEN`, `X_VERSION_STAMP_UNSCANNED`, `X_COVERAGE_BELOW`, `X_COVERAGE_PIN_STALE`, `X_COVERAGE_UNMEASURED`, `X_TEST_TYPECHECK_REGRESSED`, `X_TEST_TYPECHECK_PIN_STALE`, `X_TEST_TYPECHECK_UNSCANNED`, `X_DOC_FILE_COUNT_STALE`, `X_DOC_FILE_COUNT_UNSCANNED`, `X_DOC_RELEASE_FACT_STALE`, `X_DOC_RELEASE_FACT_UNSCANNED`, `X_DOC_PACKAGE_GRAPH_STALE`, `X_DOC_PACKAGE_GRAPH_UNSCANNED`, `X_TEST_FIX_UNRUNNABLE`, `X_TEST_FIX_PIN_STALE`, `X_TEST_FIX_UNSCANNED`, `X_TEST_THROW_NOT_THROWN`, `X_TEST_BARE_ERROR`, `X_TEST_BARE_ERROR_PIN_STALE`, `X_TEST_BARE_ERROR_UNSCANNED`, `X_SOURCE_BARE_ERROR`, `X_SOURCE_BARE_ERROR_EXEMPT_STALE`, `X_TEST_REAL_SLEEP`, `X_TEST_REAL_SLEEP_PIN_STALE`, `X_TEST_REAL_SLEEP_UNSCANNED`, `X_RELEASE_VERSION_UNSTATED`, `X_RELEASE_FLAG_UNKNOWN`, `X_RELEASE_TREE_DIRTY`, `X_RELEASE_VERSION_INVALID`, `X_RELEASE_MAJOR_WINDOW`, `X_BREAKING_ON_MAIN`, `X_RELEASE_UNDEPRECATED_REMOVAL`, `X_CHANGELOG_HIGHLIGHTS_MISSING`, `X_DOC_CHANGELOG_SECTION_INVALID`, `X_DOC_CHANGELOG_UNRELEASED_BREAKING`, `X_DOC_MIGRATION_COUNT_STALE`, `X_DOC_MIGRATION_SECTION_MISSING`, `X_DOC_MIGRATION_UNSCANNED`, `X_DOC_MIGRATION_UNPAIRED`, `X_DOC_MIGRATION_RANGE_STALE`, `X_RELEASE_UNRELEASED_MISSING`, `X_RELEASE_TAG_UNREACHABLE`, `X_RELEASE_WINDOW_UNREADABLE`, `X_RELEASE_HEAD_NOT_MAIN`, `X_HEALTH_ROW_UNREADABLE`, `X_LOCKFILE_STALE`, `X_REGISTRY_BOOTSTRAP_OWED`, `X_REGISTRY_LATEST_DRIFT`, `X_REGISTRY_UNATTESTED`, `X_REGISTRY_UNREACHABLE`, `X_REGISTRY_VERSION_BEHIND`, `X_GATE_CODE_UNDOCUMENTED`, `X_GATE_CODE_BACKLOG_STALE`, `X_SIDE_EFFECTS_*`, `X_DEAD_DOCS_HOST`, `X_DEAD_DOCS_HOST_PIN_STALE`, `X_DEAD_DOCS_HOST_UNSCANNED`, `X_SECRET_COMPARED_UNSAFELY`, `X_SECRET_COMPARE_PIN_STALE`, `X_SECRET_COMPARE_UNSCANNED`, `X_VERSION_STAMP_PIN_STALE`, `X_WORKSPACE_MANIFEST_UNREADABLE`, `X_CONFIG_KEY_READER_AMBIGUOUS`, `X_PROTO_CHAIN_INDEX`, `X_PROTO_CHAIN_INDEX_PIN_STALE`, `X_PROTO_CHAIN_INDEX_UNSCANNED`, `X_NODE_IMPORT_UNEXPLAINED`, `X_NODE_IMPORT_PIN_STALE`, `X_NODE_IMPORT_UNSCANNED`, `X_FLIGHT_RANDOM_UNINJECTED`, `X_FLIGHT_SECOND_CURVE`, `X_HELPER_COPY`, `X_NOT_IMPLEMENTED_COPY`, `X_NOT_IMPLEMENTED_COPY_UNSCANNED`, `X_FRAMEWORK_TABLE_UNAPPLIED`, `X_FRAMEWORK_TABLE_UNSCANNED`, `X_SQL_LITERAL_COPY`, `X_SQL_LITERAL_UNSCANNED`, `X_INDEX_ORDER_UNGUARDED`, `X_INDEX_ORDER_PIN_STALE`, `X_INDEX_ORDER_PIN_UNEXPLAINED`, `X_INDEX_ORDER_UNSCANNED`, `X_SKIP_CLEANUP_UNREACHED`, `X_SKIP_CLEANUP_UNSCANNED`, `X_TEST_DISCOVERY_UNSEEN`, `X_TEST_DISCOVERY_UNSCANNED`, `X_PROBE_DATABASE_FIXED`, `X_SPAWN_UNTIMED`, `X_SPAWN_TIMEOUT_PIN_STALE`, `X_SPAWN_TIMEOUT_PIN_UNEXPLAINED`, `X_SPAWN_TIMED_OUT`, `X_FETCH_UNBOUNDED`, `X_FETCH_DEADLINE_PIN_STALE`, `X_FETCH_DEADLINE_PIN_UNEXPLAINED`, `X_FINITE_BOUND_UNCHECKED`, `X_FINITE_BOUND_PIN_STALE`, `X_FINITE_BOUND_UNSCANNED`, `X_VOCABULARY_REDECLARED`, `X_VOCABULARY_UNSCANNED`, `X_FROZEN_RECORD_INFERRED`, `X_FROZEN_RECORD_UNSCANNED`, `X_CONFIG_READER_PIN_UNEXPLAINED`, `X_SECRET_COMPARE_PIN_UNEXPLAINED`, `X_PROTO_CHAIN_INDEX_PIN_UNEXPLAINED`, `X_FIX_SHELL_ARG_UNSCREENED`, `X_FIX_SHELL_ARG_PIN_STALE`, `X_FIX_SHELL_ARG_PIN_UNEXPLAINED`, `X_FIX_SHELL_ARG_UNSCANNED`, `X_BROWSER_TRANSPORT_UNSCANNED`, `X_CHANNEL_LITERAL`, `X_CHANNEL_LITERAL_UNSCANNED`, `X_SEAL_CALL_OUTSIDE_CORE`, `X_SEAL_CALL_UNSCANNED`, `X_KEYED_HASHER`, `X_KEYED_HASHER_EXEMPT_STALE`, `X_INSTRUMENT_SLOT_FORBIDDEN`, `X_INSTRUMENT_SLOT_ALLOWANCE_STALE`, `X_ADAPTER_PORT_INCOMPLETE`, `X_CLI_OUTBOUND_UNDECLARED`, `X_CLI_OUTBOUND_ALLOWANCE_STALE`, `X_PRIVATE_NAME`, `X_PRIVATE_NAMES_UNSET`, `X_GUARD_LOAD_FAILED`, `X_BUDGET_RAISE_UNSTATED`, `X_NEW_ERROR_CODE_INVALID`, `X_NEW_ERROR_CODE_EXISTS`, `X_NEW_ERROR_CODE_PATTERN_UNKNOWN`, `X_BUDGET_BASE_MISSING`, `X_PIN_RAISE_UNSTATED`, `X_PIN_BASE_MISSING`, `X_CORPUS_UNSCANNED`, `X_DOC_UNRELEASED_STALE`, `X_DOC_UNRELEASED_PIN_STALE`, `X_LLMS_TXT_DRIFT`, `X_GUARDS_DOC_DRIFT`, `X_GUARDS_DOC_UNSCANNED`, `X_CLAUDE_MD_OVERSIZE`, `X_CLAUDE_MD_UNSCANNED`, `X_CONFIG_READER_APP_UNREAD`, `X_FIX_PROSE`, `X_FIX_PROSE_PIN_STALE`, `X_FIX_PROSE_PIN_UNEXPLAINED`, `X_FIX_PROSE_UNSCANNED`, `X_DOC_PATH_DEAD`, `X_ROOT_BIN_REINTRODUCED`, `X_VERIFY_PART_UNNAMED`, `X_PLAN_STATUS_INVALID`, `X_PLAN_STATUS_UNSCANNED`, `X_URL_PATHNAME_AS_PATH`, `X_RELATIVE_PATH_NOT_POSIX`, `X_SET_COOKIE_HAND_BUILT`, `X_SET_COOKIE_PIN_STALE`, `X_SET_COOKIE_UNSCANNED`, `X_FACTORY_NAME_SPELLING`, `X_CORE_THROWER_UNCALLED`, `X_CORE_THROWER_PIN_STALE`, `X_CORE_THROWERS_UNSCANNED`, `X_SQL_EXPORT_UNREAD`, `X_SQL_EXPORT_UNSCANNED`, `X_WIKI_EXAMPLE_UNCOMPILED`, `X_WIKI_EXAMPLE_PIN_STALE`, `X_WIKI_EXAMPLE_UNSCANNED`, `X_WIKI_ANCHOR_DEAD`, `X_WIKI_ANCHOR_UNSCANNED`, `X_KNOWN_GAP_LINK_MALFORMED`, `X_KNOWN_GAP_UNSCANNED`, `X_KNOWN_GAP_UNPINNED`, `X_KNOWN_GAP_PIN_STALE`, `X_DOC_TUTORIAL_DIVERGED`, `X_DOC_UID_STALE`, `X_DOC_UID_UNSCANNED`, `X_DOC_BOUNDARY_RULES_STALE`, `X_DOC_BOUNDARY_RULES_UNSCANNED`, `X_SOURCE_HEADER_MISSING`, `X_SOURCE_HEADER_OUT_OF_CONTRACT`, `X_SOURCE_HEADER_PIN_STALE`, `X_SOURCE_HEADER_UNSCANNED`, `X_DEPENDENCY_NOT_ALLOWLISTED`, `X_DEPENDENCY_ALLOWLIST_STALE`, `X_DEPENDENCY_UNSCANNED`, `X_DEPENDENCY_RANGE_CONFLICT`) never ship, so no package may own them. See [Troubleshooting](/troubleshooting) for symptom-first triage and [CLI reference](/cli-reference) for the commands named in the fixes.

## Core and runtime

| Code | Means |
|---|---|
| [`X_ABORTED`](/errors/X_ABORTED) | operation aborted |
| [`X_TIMEOUT`](/errors/X_TIMEOUT) | operation exceeded its deadline |
| [`X_INTERNAL`](/errors/X_INTERNAL) | unexpected internal framework error |
| [`X_INVARIANT`](/errors/X_INVARIANT) | invariant violated |
| [`X_UNREACHABLE`](/errors/X_UNREACHABLE) | unreachable branch was reached |
| [`X_NOT_IMPLEMENTED`](/errors/X_NOT_IMPLEMENTED) | this driver does not implement the requested feature |
| [`X_ASYNC_CONTEXT_UNAVAILABLE`](/errors/X_ASYNC_CONTEXT_UNAVAILABLE) | async context unavailable |
| [`X_NO_CONTEXT`](/errors/X_NO_CONTEXT) | no request context is active |
| [`X_SERVICE_MISSING`](/errors/X_SERVICE_MISSING) | service is not registered on the request context |
| [`X_SERVICE_DUPLICATE`](/errors/X_SERVICE_DUPLICATE) | a service name is registered twice |
| [`X_ROLE_INVALID`](/errors/X_ROLE_INVALID) | `ROLE` is not a known runtime role |
| [`X_DRAINING`](/errors/X_DRAINING) | process is draining and refuses new work |
| [`X_SHUTDOWN_TIMEOUT`](/errors/X_SHUTDOWN_TIMEOUT) | graceful shutdown exceeded its deadline |
| [`X_FLIGHT_GATE_OVERLOADED`](/errors/X_FLIGHT_GATE_OVERLOADED) | a concurrency gate is at its ceiling and its queue is full |
| [`X_SUPERSEDED`](/errors/X_SUPERSEDED) | a later generation superseded this work |
| [`X_CLIENT_TRANSPORT_FAILED`](/errors/X_CLIENT_TRANSPORT_FAILED) | a browser request got no answer from the app |
| [`X_CLIENT_RECORD_ENVELOPE_INVALID`](/errors/X_CLIENT_RECORD_ENVELOPE_INVALID) | a response marked as a records envelope has the wrong shape |
| [`X_CLIENT_SCOPE_CHANGED`](/errors/X_CLIENT_SCOPE_CHANGED) | the page changed principal while this request was in flight |
| [`X_READINESS_CHECK_DUPLICATE`](/errors/X_READINESS_CHECK_DUPLICATE) | a readiness check name is registered twice |
| [`X_LIFECYCLE_DRAINED`](/errors/X_LIFECYCLE_DRAINED) | a drained process cannot become ready again |
| [`X_ERROR_RETRY_INVALID`](/errors/X_ERROR_RETRY_INVALID) | error retry classification is unknown or already claimed |
| [`X_ID_INVALID`](/errors/X_ID_INVALID) | value is not a valid id |
| [`X_CURSOR_INVALID`](/errors/X_CURSOR_INVALID) | pagination cursor is malformed, tampered with or from another query |
| [`X_CURSOR_SECRET_DEV`](/errors/X_CURSOR_SECRET_DEV) | cursors are signed with the shipped development key |
| [`X_ERROR_CODE_DUPLICATE`](/errors/X_ERROR_CODE_DUPLICATE) | error code registered twice |
| [`X_ERROR_REPORTER_DSN_INVALID`](/errors/X_ERROR_REPORTER_DSN_INVALID) | the error monitor DSN is malformed |
| [`X_REGISTRAR_MISSING`](/errors/X_REGISTRAR_MISSING) | no registrar is loaded for a primitive kind |
| [`X_REGISTRAR_CONFLICT`](/errors/X_REGISTRAR_CONFLICT) | two different registrars are loaded for one primitive kind |
| [`X_SECRETS_KEY_ACL_FAILED`](/errors/X_SECRETS_KEY_ACL_FAILED) | key file ACL not owner-only |
| [`X_COOKIE_INVALID`](/errors/X_COOKIE_INVALID) | a Set-Cookie value would be dropped, misread or injectable |
| [`X_OUTBOUND_TIMEOUT`](/errors/X_OUTBOUND_TIMEOUT) | an outbound HTTP call passed its deadline or went idle |
| [`X_OUTBOUND_UNREACHABLE`](/errors/X_OUTBOUND_UNREACHABLE) | an outbound HTTP call got no response |
| [`X_OUTBOUND_THROTTLED`](/errors/X_OUTBOUND_THROTTLED) | an outbound HTTP call was told to wait |
| [`X_OUTBOUND_UNAVAILABLE`](/errors/X_OUTBOUND_UNAVAILABLE) | an outbound HTTP call answered a retryable status |
| [`X_OUTBOUND_REFUSED`](/errors/X_OUTBOUND_REFUSED) | an outbound HTTP call answered a non-retryable status |
| [`X_OUTBOUND_TOO_LARGE`](/errors/X_OUTBOUND_TOO_LARGE) | an outbound HTTP response body passed its byte cap |
| [`X_OUTBOUND_HOST_BLOCKED`](/errors/X_OUTBOUND_HOST_BLOCKED) | an outbound HTTP call refused the address it would reach |
| [`X_OUTBOUND_REDIRECTED`](/errors/X_OUTBOUND_REDIRECTED) | an outbound HTTP call answered a redirect |
| [`X_OUTBOUND_RETRY_UNSAFE`](/errors/X_OUTBOUND_RETRY_UNSAFE) | a retry was asked for on a write that is not idempotent |
| [`X_OUTBOUND_BODY_INVALID`](/errors/X_OUTBOUND_BODY_INVALID) | an outbound HTTP response did not match its schema |
| [`X_BREAKER_OPEN`](/errors/X_BREAKER_OPEN) | a circuit breaker is open and refused the call |
| [`X_ERROR_DECLARATION_INVALID`](/errors/X_ERROR_DECLARATION_INVALID) | a defineError declaration is malformed |
| [`X_CLIENT_ERROR`](/errors/X_CLIENT_ERROR) | a browser reported an uncaught failure |
| [`X_HTTP_PATH_INPUT_CONFLICT`](/errors/X_HTTP_PATH_INPUT_CONFLICT) | a path parameter and the request body or query name one key with two values |
| [`X_ERROR_UNDECLARED`](/errors/X_ERROR_UNDECLARED) | a handler threw a 4xx code its errors: list does not declare |
| [`X_ACTION_ERRORS_INVALID`](/errors/X_ACTION_ERRORS_INVALID) | an errors: list names a code that cannot be declared there |
| [`X_CONTRACT_EXERCISE_ENVIRONMENT`](/errors/X_CONTRACT_EXERCISE_ENVIRONMENT) | a contract exercise was asked to run in a deployed environment |
| [`X_CONTRACT_EXERCISE_UNSCOPED`](/errors/X_CONTRACT_EXERCISE_UNSCOPED) | a contract exercise could not roll back its writes |

## Metrics

Counter, gauge and histogram live in `@ultimat3/core` (`metrics.ts`), aggregate in process, and are read through one `collectMetrics()`. The wire format is a **driver**: `MetricExporter` is the seam, the default is a no-op, and `metricsText()` renders the Prometheus/OpenMetrics scrape body behind `METRICS_PATH`. An OTLP client ships `As of 2026-08`: `otlpMetricExporter()` and `otlpSpanExporter()` speak OTLP/HTTP JSON and read `OTEL_EXPORTER_OTLP_ENDPOINT`, with no new dependency. gRPC on `:4317` is refused by design; scraping `/metrics` with an agent stays equally supported.

The three series `docker/helm` autoscales on are `http_requests_total` (the counter `rps` is derived from), `connections` and `queue_demand` — `SCALING_METRICS` in `runtime-metrics.ts` maps each `ScalingSignal` to its series, so the role table and the chart cannot drift apart.

| Code | Means |
|---|---|
| [`X_METRIC_NAME_INVALID`](/errors/X_METRIC_NAME_INVALID) | metric name is malformed, or redeclared with a different kind, bounds or observer |
| [`X_METRIC_VALUE_INVALID`](/errors/X_METRIC_VALUE_INVALID) | metric value is not recordable |
| [`X_METRIC_CARDINALITY`](/errors/X_METRIC_CARDINALITY) | a metric exceeded its series ceiling and is folding into one overflow series |
| [`X_OTLP_ENDPOINT_INVALID`](/errors/X_OTLP_ENDPOINT_INVALID) | the OTLP collector endpoint is missing or malformed |
| [`X_OTLP_HEADERS_INVALID`](/errors/X_OTLP_HEADERS_INVALID) | `OTEL_EXPORTER_OTLP_HEADERS` is malformed |
| [`X_OTLP_PROTOCOL_UNSUPPORTED`](/errors/X_OTLP_PROTOCOL_UNSUPPORTED) | the OTLP protocol requested is not OTLP/HTTP JSON |
| [`X_TELEMETRY_SAMPLER_ARG_INVALID`](/errors/X_TELEMETRY_SAMPLER_ARG_INVALID) | the trace sampling ratio is not a number between 0 and 1 |

## Images

One pipeline in `@ultimat3/core` serves `storage`, `seo` and `pwa`. It **decodes PNG, JPEG, WebP and GIF and encodes PNG, JPEG and WebP** (`DECODABLE_FORMATS` / `ENCODABLE_FORMATS`, `As of 2026-10`); AVIF and SVG are identified and measured — enough to inline `width`/`height` and keep CLS at 0 — but never synthesised. A variant in one of those formats comes from a CDN or an `ImageTransformDriver`, never from a silent passthrough.

| Code | Means |
|---|---|
| [`X_IMAGE_UNSUPPORTED`](/errors/X_IMAGE_UNSUPPORTED) | the built-in image pipeline cannot read or write this format |
| [`X_IMAGE_DECODE_FAILED`](/errors/X_IMAGE_DECODE_FAILED) | image bytes are malformed, truncated or internally inconsistent |
| [`X_IMAGE_TOO_LARGE`](/errors/X_IMAGE_TOO_LARGE) | image exceeds the pipeline pixel ceiling |

## Config and environment

| Code | Means |
|---|---|
| [`X_CONFIG_INVALID`](/errors/X_CONFIG_INVALID) | a configuration this process cannot boot on — env **or** `app.config.ts` |
| [`X_ENV_MISSING`](/errors/X_ENV_MISSING) | required environment variables are missing or invalid |
| [`X_ENVIRONMENT_INVALID`](/errors/X_ENVIRONMENT_INVALID) | `ULTIMATE_ENV` is not a known environment |
| [`X_ENV_EXAMPLE_DRIFT`](/errors/X_ENV_EXAMPLE_DRIFT) | `.env.example` does not declare every variable the schema requires |
| [`X_BUN_VERSION`](/errors/X_BUN_VERSION) | Bun is older than the framework floor |
| [`X_NOT_IN_APP`](/errors/X_NOT_IN_APP) | command must run inside an Ultimate app |
| [`X_PORT_IN_USE`](/errors/X_PORT_IN_USE) | the dev port is taken |
| [`X_DEV_ALREADY_RUNNING`](/errors/X_DEV_ALREADY_RUNNING) | another x dev already owns this checkout |
| [`X_DEV_LOCK_UNREADABLE`](/errors/X_DEV_LOCK_UNREADABLE) | the dev lock file cannot be read or removed |
| [`X_PORT_INVALID`](/errors/X_PORT_INVALID) | `PORT` is not a TCP port number |
| [`X_ROLE_UNKNOWN`](/errors/X_ROLE_UNKNOWN) | `ROLE` names something that is not a role |

## Encrypted secrets

One committed file, `secrets.enc.json`, sealed with AES-256-GCM under a 32-byte master key read from `ULTIMATE_SECRETS_KEY` first and the gitignored `.secrets.key` second. Values are decrypted into the process environment by `installSecrets()` and read back through the app's own `envSchema` — a secret is an env var, so it has one declaration, one mask and one reader. See [CLI reference](/cli-reference) for `x secrets`.

The envelope carries a **key id**: a domain-separated, truncated SHA-256 of the master key, safe to commit. It is what makes "you used the wrong key" and "this file was edited after it was sealed" two different codes instead of one unexplained decryption failure.

| Code | Means |
|---|---|
| [`X_SECRETS_KEY_MISSING`](/errors/X_SECRETS_KEY_MISSING) | no master key for the encrypted secrets file |
| [`X_SECRETS_KEY_INVALID`](/errors/X_SECRETS_KEY_INVALID) | the master key is not 32 bytes of hex |
| [`X_SECRETS_KEY_MISMATCH`](/errors/X_SECRETS_KEY_MISMATCH) | the secrets file was sealed with a different master key |
| [`X_SECRETS_FILE_MISSING`](/errors/X_SECRETS_FILE_MISSING) | the encrypted secrets file does not exist |
| [`X_SECRETS_FILE_INVALID`](/errors/X_SECRETS_FILE_INVALID) | the encrypted secrets file is not a readable envelope |
| [`X_SECRETS_TAMPERED`](/errors/X_SECRETS_TAMPERED) | the secrets file failed its authentication tag |
| [`X_SECRETS_PLAINTEXT_INVALID`](/errors/X_SECRETS_PLAINTEXT_INVALID) | the decrypted secrets are not a flat map of env values |
| [`X_SECRETS_EDITOR_MISSING`](/errors/X_SECRETS_EDITOR_MISSING) | no `$EDITOR` to open the decrypted secrets in |
| [`X_SECRETS_EDIT_FAILED`](/errors/X_SECRETS_EDIT_FAILED) | the editor exited non-zero, so nothing was resealed |
| [`X_SEAL_KEY_MISSING`](/errors/X_SEAL_KEY_MISSING) | no master key to seal or open a value with |
| [`X_SEAL_KEY_UNKNOWN`](/errors/X_SEAL_KEY_UNKNOWN) | a sealed value names a master key this process does not declare |
| [`X_SEAL_INVALID`](/errors/X_SEAL_INVALID) | a sealed value did not authenticate, or is not a sealed value |
| [`X_WORKSPACE_DEP_UNDECLARED`](/errors/X_WORKSPACE_DEP_UNDECLARED) | a workspace imports another workspace its own `package.json` does not declare |
| [`X_PACKAGE_DUPLICATED`](/errors/X_PACKAGE_DUPLICATED) | two copies of one registry-holding framework package (`@ultimat3/i18n`, `@ultimat3/policy`, `@ultimat3/entity`) are installed in one app |
| [`X_SHOT_BROWSER_MISSING`](/errors/X_SHOT_BROWSER_MISSING) | `x shot` has no browser to launch |
| [`X_SHOT_HOST_REFUSED`](/errors/X_SHOT_HOST_REFUSED) | x shot was asked to open a host outside the run's allow list |
| [`X_SHOT_ELEMENT_MISSING`](/errors/X_SHOT_ELEMENT_MISSING) | no element matched the selector before the deadline |
| [`X_SHOT_ELEMENT_UNREADY`](/errors/X_SHOT_ELEMENT_UNREADY) | the element matched and never became ready to act on |
| [`X_SHOT_KEY_INVALID`](/errors/X_SHOT_KEY_INVALID) | a key chord the browser cannot press |
| [`X_GH_UNAVAILABLE`](/errors/X_GH_UNAVAILABLE) | the GitHub CLI is not runnable from here |
| [`X_GH_NOT_AUTHENTICATED`](/errors/X_GH_NOT_AUTHENTICATED) | `gh` holds no credentials for this host |
| [`X_GH_COMMAND_FAILED`](/errors/X_GH_COMMAND_FAILED) | a `gh` invocation exited non-zero |
| [`X_GH_RESPONSE_INVALID`](/errors/X_GH_RESPONSE_INVALID) | `gh`'s output is not the shape the command reads |
| [`X_PR_NOT_FOUND`](/errors/X_PR_NOT_FOUND) | no pull request for this checkout |
| [`X_CI_RUN_NOT_FOUND`](/errors/X_CI_RUN_NOT_FOUND) | no workflow run for this branch |
| [`X_SEAL_RESEAL_PENDING`](/errors/X_SEAL_RESEAL_PENDING) | sealed columns still hold values under a retired master key |

## Schema and validation

| Code | Means |
|---|---|
| [`X_VALIDATION_FAILED`](/errors/X_VALIDATION_FAILED) | value did not match its schema |
| [`X_SCHEMA_UNSUPPORTED`](/errors/X_SCHEMA_UNSUPPORTED) | the active schema provider cannot do this |
| [`X_SCHEMA_DISCRIMINANT_INVALID`](/errors/X_SCHEMA_DISCRIMINANT_INVALID) | a discriminated union member can never be dispatched to |
| [`X_SCHEMA_DEFAULT_UNSHAREABLE`](/errors/X_SCHEMA_DEFAULT_UNSHAREABLE) | a schema default cannot be copied per parse |
| [`X_SCHEMA_DEFAULT_INVALID`](/errors/X_SCHEMA_DEFAULT_INVALID) | a schema default fails its own schema |
| [`X_SCHEMA_BOUNDS_INVALID`](/errors/X_SCHEMA_BOUNDS_INVALID) | an array bound no array can satisfy |
| [`X_SCHEMA_SENSITIVE_OUTPUT`](/errors/X_SCHEMA_SENSITIVE_OUTPUT) | a sensitive field is reachable from an output |
| [`X_SCHEMA_ISSUE_CAP_INVALID`](/errors/X_SCHEMA_ISSUE_CAP_INVALID) | a validation issue cap no list can meet |

## HTTP

| Code | Means |
|---|---|
| [`X_ROUTE_NOT_FOUND`](/errors/X_ROUTE_NOT_FOUND) | no route matches this request |
| [`X_METHOD_NOT_ALLOWED`](/errors/X_METHOD_NOT_ALLOWED) | route exists but not for this method |
| [`X_PATH_INVALID`](/errors/X_PATH_INVALID) | a path segment is not valid percent-encoding |
| [`X_ROUTE_CONFLICT`](/errors/X_ROUTE_CONFLICT) | two routes claim the same path |
| [`X_BODY_INVALID`](/errors/X_BODY_INVALID) | request body failed its schema |
| [`X_UNAUTHENTICATED`](/errors/X_UNAUTHENTICATED) | no authenticated actor for this request |
| [`X_FORBIDDEN`](/errors/X_FORBIDDEN) | policy denied this actor |
| [`X_RATE_LIMITED`](/errors/X_RATE_LIMITED) | rate limit exhausted for this key |
| [`X_RATE_LIMIT_NOT_SHARED`](/errors/X_RATE_LIMIT_NOT_SHARED) | the app declared a fleet-wide rate limit and the store keeps its counters per process |
| [`X_RATE_LIMIT_BUCKET_CONFLICT`](/errors/X_RATE_LIMIT_BUCKET_CONFLICT) | one bucket has two declarations that disagree |
| [`X_RATE_LIMIT_BUCKET_UNBOUND`](/errors/X_RATE_LIMIT_BUCKET_UNBOUND) | the installed limiter does not hold a bucket a route declares |
| [`X_RATE_LIMIT_SCOPE_UNSET`](/errors/X_RATE_LIMIT_SCOPE_UNSET) | the deployment has not said where the rate limiter keeps its counters |
| [`X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN`](/errors/X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN) | the tenant allowance names a bucket nothing declares |
| [`X_RATE_LIMIT_INVALID`](/errors/X_RATE_LIMIT_INVALID) | a declared rate limit computes to numbers the limiter cannot run on |
| [`X_RATE_LIMIT_STORE_UNAVAILABLE`](/errors/X_RATE_LIMIT_STORE_UNAVAILABLE) | the shared rate-limit store did not answer, so nothing decided |
| [`X_TRUST_PROXY_UNSET`](/errors/X_TRUST_PROXY_UNSET) | proxy headers are trusted without saying how many proxies are in front |
| [`X_OVERLOADED`](/errors/X_OVERLOADED) | in-flight requests are at the configured ceiling |
| [`X_CSRF_BLOCKED`](/errors/X_CSRF_BLOCKED) | an unsafe request that did not prove same-origin |
| [`X_WEBHOOK_SIGNATURE_INVALID`](/errors/X_WEBHOOK_SIGNATURE_INVALID) | the inbound webhook is not signed by the holder of this secret |
| [`X_WEBHOOK_SIGNATURE_STALE`](/errors/X_WEBHOOK_SIGNATURE_STALE) | the inbound webhook is signed correctly and is too old to accept |
| [`X_BUILD_SKEW`](/errors/X_BUILD_SKEW) | client build id does not match the server build id |
| [`X_SERVER_NOT_STARTED`](/errors/X_SERVER_NOT_STARTED) | server handle used before `start()` |
| [`X_PIPELINE_NO_RESPONSE`](/errors/X_PIPELINE_NO_RESPONSE) | a pipeline stage produced no response |
| [`X_PIPELINE_FINALIZE_FAILED`](/errors/X_PIPELINE_FINALIZE_FAILED) | a finalize stage threw instead of finishing the response |
| [`X_NO_REQUEST`](/errors/X_NO_REQUEST) | the inbound request is not in scope here |
| [`X_ERROR_STATUS_INVALID`](/errors/X_ERROR_STATUS_INVALID) | an error code cannot be mapped to that status |
| [`X_PROBLEM_META_INVALID`](/errors/X_PROBLEM_META_INVALID) | a problem document cannot carry that meta declaration |
| [`X_CORS_CONFIG_INVALID`](/errors/X_CORS_CONFIG_INVALID) | the cors config can never produce a working response |
| [`X_CSP_DIRECTIVE_INVALID`](/errors/X_CSP_DIRECTIVE_INVALID) | a csp extension would emit something other than the directive it names |
| [`X_BEARER_MOUNT_INVALID`](/errors/X_BEARER_MOUNT_INVALID) | a bearer mount declaration cannot be served as written |
| [`X_RATE_LIMIT_STORE_TIMEOUT`](/errors/X_RATE_LIMIT_STORE_TIMEOUT) | the shared rate-limit store did not answer inside its own deadline |
| [`X_EXERCISE_REQUEST_INVALID`](/errors/X_EXERCISE_REQUEST_INVALID) | an exercise entry's request is not one a browser could send |
| [`X_BODY_TOO_LARGE`](/errors/X_BODY_TOO_LARGE) | request body over the transport ceiling |

## Policy and authz

A denial is `X_FORBIDDEN`, above — `@ultimat3/policy` owns it and every surface adapter throws it, so there is one code for "the policy said no" wherever it was decided.

| Code | Means |
|---|---|
| [`X_POLICY_MISSING`](/errors/X_POLICY_MISSING) | an action was declared without a policy |
| [`X_POLICY_CLAUSE_EMPTY`](/errors/X_POLICY_CLAUSE_EMPTY) | a policy combinator was built with no clauses |
| [`X_PERMISSION_UNKNOWN`](/errors/X_PERMISSION_UNKNOWN) | permission string is not in the permission set |
| [`X_POLICY_SURFACE_UNKNOWN`](/errors/X_POLICY_SURFACE_UNKNOWN) | enforce() was handed a surface no adapter answers to |
| [`X_ROLE_REDEFINED`](/errors/X_ROLE_REDEFINED) | two modules define the same role differently |
| [`X_TENANCY_UNSCOPED`](/errors/X_TENANCY_UNSCOPED) | a tenant-scoped query has no org predicate |
| [`X_TENANCY_ACTOR_MISMATCH`](/errors/X_TENANCY_ACTOR_MISMATCH) | a call named a tenant other than the actor's — as a query predicate, or as the tenant column of a row being written |
| [`X_TENANCY_ACTOR_ORG_REQUIRED`](/errors/X_TENANCY_ACTOR_ORG_REQUIRED) | the acting actor carries no tenant |
| [`X_TENANCY_CROSS_DENIED`](/errors/X_TENANCY_CROSS_DENIED) | a cross-tenant read was entered without the capability |
| [`X_ACTION_POLICY_MISSING`](/errors/X_ACTION_POLICY_MISSING) | an action was registered without a policy |
| [`X_QUERY_POLICY_MISSING`](/errors/X_QUERY_POLICY_MISSING) | a query was registered without a policy |
| [`X_QUERY_NOT_PAGEABLE`](/errors/X_QUERY_NOT_PAGEABLE) | a read returned rows with no id, so a cursor cannot name a position |
| [`X_QUERY_COLUMN_UNSELECTED`](/errors/X_QUERY_COLUMN_UNSELECTED) | a read filters or sorts on a column its rows do not carry |
| [`X_CURSOR_VALUE_UNSUPPORTED`](/errors/X_CURSOR_VALUE_UNSUPPORTED) | a sort value cannot be carried in a cursor |
| [`X_AGGREGATE_UNSUPPORTED`](/errors/X_AGGREGATE_UNSUPPORTED) | that column has no aggregate both drivers can answer alike |
| [`X_AGGREGATE_MIXED_CURRENCY`](/errors/X_AGGREGATE_MIXED_CURRENCY) | an amount was aggregated across currencies |
| [`X_APPROXIMATE_COUNT_FILTERED`](/errors/X_APPROXIMATE_COUNT_FILTERED) | an estimate was asked of a filtered chain |
| [`X_QUERY_CACHE_TTL_INVALID`](/errors/X_QUERY_CACHE_TTL_INVALID) | a query declares a cache `ttlMs` no tier can hold |
| [`X_QUERY_INPUT_UNENCODABLE`](/errors/X_QUERY_INPUT_UNENCODABLE) | a query input cannot be carried in a query string |
| [`X_QUERY_SUBSCRIBES_INVALID`](/errors/X_QUERY_SUBSCRIBES_INVALID) | a query declares subscribed relations no live read can use |
| [`X_QUERY_SUBSCRIBES_DRIFT`](/errors/X_QUERY_SUBSCRIBES_DRIFT) | a live query subscribes to a relation its own sql never reads |
| [`X_QUERY_SUBSCRIBES_UNKNOWN`](/errors/X_QUERY_SUBSCRIBES_UNKNOWN) | a live query subscribes to a table no entity declares |

## Auth and sessions

| Code | Means |
|---|---|
| [`X_SESSION_EXPIRED`](/errors/X_SESSION_EXPIRED) | session passed its idle or absolute expiry |
| [`X_MFA_REQUIRED`](/errors/X_MFA_REQUIRED) | password proven, second factor outstanding |
| [`X_MFA_SECRET_INVALID`](/errors/X_MFA_SECRET_INVALID) | a TOTP secret that is not RFC 4648 base32, so it decodes to zero bytes |
| [`X_OAUTH_STATE_INVALID`](/errors/X_OAUTH_STATE_INVALID) | state, nonce or PKCE verifier did not match |
| [`X_OAUTH_EXCHANGE_FAILED`](/errors/X_OAUTH_EXCHANGE_FAILED) | the provider refused the exchange or returned no usable identity |
| [`X_OAUTH_TOKEN_INVALID`](/errors/X_OAUTH_TOKEN_INVALID) | the id token failed its signature, issuer, audience or expiry check |
| [`X_OAUTH_PROVIDER_DUPLICATE`](/errors/X_OAUTH_PROVIDER_DUPLICATE) | two oauth providers were registered under one id |
| [`X_OAUTH_PROVIDER_UNKNOWN`](/errors/X_OAUTH_PROVIDER_UNKNOWN) | the URL named a provider this app has not enabled |
| [`X_OAUTH_DENIED`](/errors/X_OAUTH_DENIED) | the user or the provider declined the authorization |
| [`X_PASSWORD_WEAK`](/errors/X_PASSWORD_WEAK) | strength check rejected the password |
| [`X_ACCOUNT_LOCKED`](/errors/X_ACCOUNT_LOCKED) | per-ip, per-account or per-org bucket is inside its lockout |
| [`X_AUTH_LIMITER_NOT_SHARED`](/errors/X_AUTH_LIMITER_NOT_SHARED) | the app declared a fleet-wide credential throttle and the limiter keeps its counters per process |
| [`X_AUTH_LIMITER_POLICY_MISMATCH`](/errors/X_AUTH_LIMITER_POLICY_MISMATCH) | a custom credential limiter enforces different numbers than the app declared |
| [`X_API_KEY_INVALID`](/errors/X_API_KEY_INVALID) | key unknown, revoked, expired, wrong, or owned by a user who is gone or disabled |
| [`X_AUTH_WRITE_FAILED`](/errors/X_AUTH_WRITE_FAILED) | an adapter write returned no row, so it cannot be confirmed |
| [`X_MFA_SECRET_UNSEALED`](/errors/X_MFA_SECRET_UNSEALED) | a stored totp secret is not sealed, so it is never read as one |
| [`X_AUTH_SIGN_IN_UNCONFIGURED`](/errors/X_AUTH_SIGN_IN_UNCONFIGURED) | a people-facing role started with no sign-in settings outside development and test |
| [`X_AUTH_SERVER_INVALID`](/errors/X_AUTH_SERVER_INVALID) | the authorization server was configured with a field it cannot run on |
| [`X_AUTH_CONSENT_INVALID`](/errors/X_AUTH_CONSENT_INVALID) | a consent was approved for a request the authorization server refuses |
| [`X_AUTH_GRANT_DISABLED`](/errors/X_AUTH_GRANT_DISABLED) | a token request named a grant this authorization server does not enable |
| [`X_VERIFICATION_PURPOSE_INVALID`](/errors/X_VERIFICATION_PURPOSE_INVALID) | a verification purpose was declared twice or without a template |
| [`X_VERIFICATION_PURPOSE_UNKNOWN`](/errors/X_VERIFICATION_PURPOSE_UNKNOWN) | a verification token was issued or consumed for a purpose nothing declared |
| [`X_PASSKEY_INVALID`](/errors/X_PASSKEY_INVALID) | a passkey ceremony response failed its signature, origin, rp id, flag or counter check |
| [`X_PASSKEY_CHALLENGE_EXPIRED`](/errors/X_PASSKEY_CHALLENGE_EXPIRED) | a passkey ceremony named a challenge that is unknown, already used or past its ttl |
| [`X_PASSKEY_STEP_UP_REQUIRED`](/errors/X_PASSKEY_STEP_UP_REQUIRED) | a sensitive action ran without a fresh user-verified passkey proof for its digest |
| [`X_SAML_RESPONSE_INVALID`](/errors/X_SAML_RESPONSE_INVALID) | a saml response failed its signature, wrapping, audience, recipient, time, InResponseTo or replay check |
| [`X_SAML_METADATA_INVALID`](/errors/X_SAML_METADATA_INVALID) | saml IdP metadata has no entity id, HTTP-Redirect sign-on endpoint or signing certificate |
| [`X_IDENTITY_PROVIDER_UNKNOWN`](/errors/X_IDENTITY_PROVIDER_UNKNOWN) | the URL named an identity provider the sso routes were not given |

`GET /auth/sso/<provider>` is the app's route to mount, not one the framework serves. Every OAuth fix above is reachable only where the host routes matching requests to `oauthLogin(auth).start.handle`; `oauthLogin()` supplies the descriptors and nothing else mounts them. The thrown `fix:` and the descriptor's `path` both read the one declaration in `oauth-paths.ts`, so the string cannot go stale — but `As of 2026-08` `serve.ts` composes a fixed set of route tables with no seam for a raw `Route`, so nothing `x new` scaffolds mounts the pair and an app that has not mounted it itself answers that path with a 404.

## Entity and database

| Code | Means |
|---|---|
| [`X_RECORD_KEY_MISSING`](/errors/X_RECORD_KEY_MISSING) | a row reached its record key without a primary-key value |
| [`X_DB_DRIFT`](/errors/X_DB_DRIFT) | schema differs from migrations |
| [`X_DB_SCHEMA_UNMIGRATED`](/errors/X_DB_SCHEMA_UNMIGRATED) | an entity declaration no migration recorded |
| [`X_DB_SCHEMA_UNDECLARED`](/errors/X_DB_SCHEMA_UNDECLARED) | a migration records schema no entity declares |
| [`X_ENTITY_DUPLICATE`](/errors/X_ENTITY_DUPLICATE) | two entities claim the same name |
| [`X_INVARIANT_VIOLATED`](/errors/X_INVARIANT_VIOLATED) | a domain invariant rejected this row |
| [`X_NOT_FOUND`](/errors/X_NOT_FOUND) | no row for that id |
| [`X_WRITE_UNFILTERED`](/errors/X_WRITE_UNFILTERED) | `deleteWhere()` or `updateWhere()` named no filter columns |
| [`X_PATCH_EMPTY`](/errors/X_PATCH_EMPTY) | `updateWhere()` named no columns to write |
| [`X_PRELOAD_UNKNOWN_RELATION`](/errors/X_PRELOAD_UNKNOWN_RELATION) | no relation of that name on this entity |
| [`X_N_PLUS_ONE_QUERY`](/errors/X_N_PLUS_ONE_QUERY) | a read repeated once per row |
| [`X_N_PLUS_ONE_WRITE`](/errors/X_N_PLUS_ONE_WRITE) | a write repeated once per row |
| [`X_SEARCH_UNDECLARED`](/errors/X_SEARCH_UNDECLARED) | this entity has no searchable column |
| [`X_SEARCH_IN_MEMORY`](/errors/X_SEARCH_IN_MEMORY) | the in-memory driver cannot answer a full-text match |
| [`X_STATE_UNDECLARED`](/errors/X_STATE_UNDECLARED) | that column declares no state machine |
| [`X_STATE_TRANSITION_ILLEGAL`](/errors/X_STATE_TRANSITION_ILLEGAL) | the machine has no such transition |
| [`X_STATE_CONFLICT`](/errors/X_STATE_CONFLICT) | the row changed after the read this transition was decided on |
| [`X_DB_UNAVAILABLE`](/errors/X_DB_UNAVAILABLE) | cannot reach the database |
| [`X_DB_SCHEMA_STALE`](/errors/X_DB_SCHEMA_STALE) | the statement names a table or column the database does not have |
| [`X_DB_STATEMENT_FAILED`](/errors/X_DB_STATEMENT_FAILED) | the database refused the statement |
| [`X_DB_UNIQUE_VIOLATION`](/errors/X_DB_UNIQUE_VIOLATION) | a unique constraint rejected the row |
| [`X_DB_FOREIGN_KEY_VIOLATION`](/errors/X_DB_FOREIGN_KEY_VIOLATION) | a foreign key constraint rejected the row |
| [`X_DB_SERIALIZATION_FAILURE`](/errors/X_DB_SERIALIZATION_FAILURE) | the transaction lost a serialization race |
| [`X_DB_STATEMENT_TIMEOUT`](/errors/X_DB_STATEMENT_TIMEOUT) | the statement ran past its `statement_timeout` |
| [`X_DB_LOCK_TIMEOUT`](/errors/X_DB_LOCK_TIMEOUT) | the statement waited past its `lock_timeout` |
| [`X_DB_POOL_EXHAUSTED`](/errors/X_DB_POOL_EXHAUSTED) | no connection was available |
| [`X_DB_DRAIN_TIMEOUT`](/errors/X_DB_DRAIN_TIMEOUT) | the pool did not drain inside its shutdown budget |
| [`X_MIGRATION_CONFLICT`](/errors/X_MIGRATION_CONFLICT) | the migration ledger disagrees with this build |
| [`X_MIGRATE_CONCURRENT`](/errors/X_MIGRATE_CONCURRENT) | another migrator holds the migration lock |
| [`X_MIGRATION_IRREVERSIBLE`](/errors/X_MIGRATION_IRREVERSIBLE) | this migration cannot be reversed without data loss |
| [`X_MIGRATION_DESTRUCTIVE`](/errors/X_MIGRATION_DESTRUCTIVE) | this migration destroys data and does not say so |
| [`X_MIGRATION_UNGENERATABLE`](/errors/X_MIGRATION_UNGENERATABLE) | this migration holds SQL no declaration carries and does not say so |
| [`X_MIGRATION_VIEW_DEPENDS`](/errors/X_MIGRATION_VIEW_DEPENDS) | a view is compiled against a column this migration retypes |
| [`X_MIGRATION_SNAPSHOT_MISSING`](/errors/X_MIGRATION_SNAPSHOT_MISSING) | the newest migration records no schema snapshot |
| [`X_BRANCH_EXISTS`](/errors/X_BRANCH_EXISTS) | that branch database already exists |
| [`X_SQL_UNSAFE`](/errors/X_SQL_UNSAFE) | SQL was built by string interpolation |
| [`X_REPO_CLIENT_PINNED`](/errors/X_REPO_CLIENT_PINNED) | a repository pinned to its own client cannot join the open transaction |
| [`X_DB_GEN_FAILED`](/errors/X_DB_GEN_FAILED) / [`X_DB_MIGRATE_FAILED`](/errors/X_DB_MIGRATE_FAILED) | the `x db` step failed for a reason no framework error claimed |
| [`X_DB_BRANCH_FAILED`](/errors/X_DB_BRANCH_FAILED) | `x db branch` refused, or failed for a reason no framework error claimed |
| [`X_DB_STUDIO_FAILED`](/errors/X_DB_STUDIO_FAILED) | reserved, not thrown — `x db studio` is **planned and unreleased**, and exits `X_NOT_IMPLEMENTED`. It shelled out to `bunx drizzle-kit studio`, a second schema engine for one subcommand |
| [`X_SCHEMA_DUMP_DRIFT`](/errors/X_SCHEMA_DUMP_DRIFT) | the committed schema dump is not what the migrations produce |
| [`X_ENTITY_SEALED_PREDICATE`](/errors/X_ENTITY_SEALED_PREDICATE) | a sealed column is read by a predicate, an order or a rule the database evaluates |
| [`X_ENTITY_SEALED_IN_VIEW`](/errors/X_ENTITY_SEALED_IN_VIEW) | a sealed column is named in a view |
| [`X_DB_TRANSACTION_ABORTED`](/errors/X_DB_TRANSACTION_ABORTED) | the server rolled the transaction back |
| [`X_DB_COMMIT_UNKNOWN`](/errors/X_DB_COMMIT_UNKNOWN) | the connection was lost while COMMIT was in flight |
| [`X_DB_SIBLING_SCOPE_TIMEOUT`](/errors/X_DB_SIBLING_SCOPE_TIMEOUT) | a nested transaction scope waited too long for its sibling |
| [`X_ENTITY_APPEND_ONLY`](/errors/X_ENTITY_APPEND_ONLY) | an append-only entity was asked to rewrite or remove a row |
| [`X_APPEND_ONLY_TRIGGER_MISSING`](/errors/X_APPEND_ONLY_TRIGGER_MISSING) | an append-only table has lost its refusing trigger |
| [`X_MIGRATION_APPEND_ONLY_BACKFILL`](/errors/X_MIGRATION_APPEND_ONLY_BACKFILL) | a NOT NULL column added to an append-only table needs a default |
| [`X_ENTITY_OPERATOR_UNKNOWN`](/errors/X_ENTITY_OPERATOR_UNKNOWN) | a predicate names an operator outside the vocabulary |
| [`X_MIGRATION_CONCURRENT_IN_TRANSACTION`](/errors/X_MIGRATION_CONCURRENT_IN_TRANSACTION) | a concurrent index statement is in a migration that runs inside a transaction |
| [`X_DB_TRANSACTION_CLOSED`](/errors/X_DB_TRANSACTION_CLOSED) | statement on a finished transaction |
| [`X_MIGRATION_ROLLING_UNSAFE`](/errors/X_MIGRATION_ROLLING_UNSAFE) | this drop or rename would break the pods still running the old release |
| [`X_LOCK_UNSUPPORTED`](/errors/X_LOCK_UNSUPPORTED) | a repository has no lock |
| [`X_DB_POOLER_OPTIONS_REFUSED`](/errors/X_DB_POOLER_OPTIONS_REFUSED) | the connection pooler refused the libpq options a pool connects with |
| [`X_DB_POOLER_SESSION_REQUIRED`](/errors/X_DB_POOLER_SESSION_REQUIRED) | this role needs one backend per session, and a transaction pooler gives it none |
| [`X_DB_STATEMENT_BOUND_LOST`](/errors/X_DB_STATEMENT_BOUND_LOST) | the session's statement bound is not the role's |
| [`X_TEST_DRIVER_CLIENT_CHANGED`](/errors/X_TEST_DRIVER_CLIENT_CHANGED) | The installed client changed inside a testDriver() transaction |
| [`X_ENTITY_TENANT_UNDECLARED`](/errors/X_ENTITY_TENANT_UNDECLARED) | a child of a tenant-owned table has no tenant |
| [`X_DB_STATEMENT_BOUND_INVALID`](/errors/X_DB_STATEMENT_BOUND_INVALID) | a statement bound is not a whole positive number of ms under the role bound |
| [`X_MIGRATION_CONCURRENT_PARTITIONED`](/errors/X_MIGRATION_CONCURRENT_PARTITIONED) | a concurrent index build names a partitioned table |
| [`X_DB_ROW_SECURITY_BYPASSED`](/errors/X_DB_ROW_SECURITY_BYPASSED) | row security is on and the serving role is exempt from it |
| [`X_DB_ROW_SECURITY_DRIFT`](/errors/X_DB_ROW_SECURITY_DRIFT) | a tenant table and database.rowSecurity disagree about its policy |
| [`X_KEYSET_NULL_KEY`](/errors/X_KEYSET_NULL_KEY) | a keyset page holds a null in one of its sort keys |
| [`X_MIGRATION_ROLLBACK_DESTRUCTIVE`](/errors/X_MIGRATION_ROLLBACK_DESTRUCTIVE) | a rollback would serve an older build over a destructive migration |
| [`X_ENTITY_SERIES_UNSUPPORTED`](/errors/X_ENTITY_SERIES_UNSUPPORTED) | a repository has no series |
| [`X_ENTITY_SERIES_INVALID`](/errors/X_ENTITY_SERIES_INVALID) | a time series asked for something no bucket can answer |
| [`X_ENTITY_VIEW_READ_ONLY`](/errors/X_ENTITY_VIEW_READ_ONLY) | a view entity was asked to write a row |
| [`X_ENTITY_RETAIN_UNINDEXED`](/errors/X_ENTITY_RETAIN_UNINDEXED) | entity({ retain }) names a column no index leads with |
| [`X_ENTITY_COUNTS_INVALID`](/errors/X_ENTITY_COUNTS_INVALID) | references(…, { countedIn }) names no integer of its parent, or is no key to its primary key |
| [`X_ENTITY_RETAIN_INVALID`](/errors/X_ENTITY_RETAIN_INVALID) | entity({ retain }) has no window, sits beside appendOnly, or is on a partitioned table |
| [`X_LIFECYCLE_TRIGGER_MISSING`](/errors/X_LIFECYCLE_TRIGGER_MISSING) | a history or counter trigger the migrations created is missing from the database |
| [`X_ENTITY_READ_ONLY`](/errors/X_ENTITY_READ_ONLY) | a read-only entity was asked to write a row |
| [`X_DRIVER_UNSUPPORTED`](/errors/X_DRIVER_UNSUPPORTED) | a custom driver was asked for a capability it does not declare |
| [`X_DRIVER_CAPABILITY_MISSING`](/errors/X_DRIVER_CAPABILITY_MISSING) | a custom driver declares a capability its raw repo does not implement |
| [`X_DRIVER_ROW_OUT_OF_SCOPE`](/errors/X_DRIVER_ROW_OUT_OF_SCOPE) | a custom driver returned a row outside the plan it was given |
| [`X_MIGRATION_PARTITION_CHANGE`](/errors/X_MIGRATION_PARTITION_CHANGE) | an existing table gained or lost entity({ partitionBy }) |
| [`X_ENTITY_PARTITION_INVALID`](/errors/X_ENTITY_PARTITION_INVALID) | entity({ partitionBy }) declares a partitioning Postgres cannot build |

## Actions

| Code | Means |
|---|---|
| [`X_MUTATOR_CLOCK_MISSING`](/errors/X_MUTATOR_CLOCK_MISSING) | a mutator declares conflict: 'last-write-wins' and its entity has no number clock column |
| [`X_ACTION_DUPLICATE`](/errors/X_ACTION_DUPLICATE) | two actions registered under one name |
| [`X_ACTION_PATH_DUPLICATE`](/errors/X_ACTION_PATH_DUPLICATE) | two actions derive one HTTP path |
| [`X_INPUT_INVALID`](/errors/X_INPUT_INVALID) | input failed the primitive's schema — an action's, and a query's too |
| [`X_OUTPUT_INVALID`](/errors/X_OUTPUT_INVALID) | the handler returned a value its `output` schema rejects |
| [`X_ACTION_FOREIGN`](/errors/X_ACTION_FOREIGN) | a value that is not an action was projected as one |
| [`X_ACTION_UNREGISTERED`](/errors/X_ACTION_UNREGISTERED) | an action was projected before it was registered, so it has no name |
| [`X_IDEMPOTENCY_CONFLICT`](/errors/X_IDEMPOTENCY_CONFLICT) | idempotency key reused with a different payload, or still in flight |
| [`X_IDEMPOTENCY_KEY_INVALID`](/errors/X_IDEMPOTENCY_KEY_INVALID) | an `Idempotency-Key` header was sent that cannot identify one request |
| [`X_IDEMPOTENCY_NOT_SHARED`](/errors/X_IDEMPOTENCY_NOT_SHARED) | idempotency is declared fleet-wide and the installed store is per-process |
| [`X_IDEMPOTENCY_STATUS_UNKNOWN`](/errors/X_IDEMPOTENCY_STATUS_UNKNOWN) | an idempotency record holds a status this build cannot read |
| [`X_IDEMPOTENCY_REPLAYED_FAILURE`](/errors/X_IDEMPOTENCY_REPLAYED_FAILURE) | a retried `Idempotency-Key` replays a first attempt that failed after it may have committed |
| [`X_CONTRACT_DRIFT`](/errors/X_CONTRACT_DRIFT) | client and server disagree about the contract |
| [`X_ACTION_DEPRECATION_INVALID`](/errors/X_ACTION_DEPRECATION_INVALID) | an action declares a deprecation whose dates cannot be rendered |
| [`X_AUDIT_SINK_MISSING`](/errors/X_AUDIT_SINK_MISSING) | an action declares `audit: true` and no sink is installed |
| [`X_AUDIT_SINK_FAILED`](/errors/X_AUDIT_SINK_FAILED) | an action ran and its sink refused the record, so the change is unrecorded |
| [`X_RPC_FAILED`](/errors/X_RPC_FAILED) | an RPC call failed without a problem+json body |
| [`X_ACTION_HTTP_PATH_INVALID`](/errors/X_ACTION_HTTP_PATH_INVALID) | an action's pinned http.path is not a valid path or :param template |
| [`X_ACTION_PATH_STYLE_INVALID`](/errors/X_ACTION_PATH_STYLE_INVALID) | defineApi's http.pathStyle is not a known style |
| [`X_OPENAPI_CONFIG_INVALID`](/errors/X_OPENAPI_CONFIG_INVALID) | defineApi's openapi block cannot produce a valid document |
| [`X_ACTION_PATH_DERIVED_EARLY`](/errors/X_ACTION_PATH_DERIVED_EARLY) | a path was derived before pathStyle changed |
| [`X_MUTATOR_NOT_IDEMPOTENT`](/errors/X_MUTATOR_NOT_IDEMPOTENT) | a mutator is declared without idempotent: true |
| [`X_IDEMPOTENCY_RESERVATION_LOST`](/errors/X_IDEMPOTENCY_RESERVATION_LOST) | an idempotent action's reservation was taken over before its transaction could settle it |
| [`X_IDEMPOTENT_REPLAY_REDACTED`](/errors/X_IDEMPOTENT_REPLAY_REDACTED) | an idempotent replay would return a field redacted at rest |
| [`X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE`](/errors/X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE) | an idempotent action's answer cannot be stored as JSON, so no retry could replay it |
| [`X_IDEMPOTENCY_RUN_CEILING`](/errors/X_IDEMPOTENCY_RUN_CEILING) | a keyed run passed its hard ceiling |
| [`X_CONTRACT_DEFECT`](/errors/X_CONTRACT_DEFECT) | a generated legal input made a handler fail |
| [`X_CONTRACT_EXERCISE_UNREACHED`](/errors/X_CONTRACT_EXERCISE_UNREACHED) | no generated run reached the handler |
| [`X_CONTRACT_EXERCISE_UNDECLARED`](/errors/X_CONTRACT_EXERCISE_UNDECLARED) | .contract() on a non-public action names no exercise |
| [`X_ACTION_STREAM_INVALID`](/errors/X_ACTION_STREAM_INVALID) | a streaming action broke its stream contract |
| [`X_METER_EXCEEDED`](/errors/X_METER_EXCEEDED) | an action's usage meter is spent for this period |
| [`X_METER_INVALID`](/errors/X_METER_INVALID) | an action's meter cannot be counted against |

A code the SERVER threw keeps its own code on the client — including one this table never
lists, because an app declares its own through `defineError`. The typed client rebuilds
it as a `RemoteActionError` marked `meta.origin: 'remote'` — with the document's declared `meta`
keys put back beside that marker, `As of 2026-09-05` — linked to the first of the server's
`docs` and RFC-9457 `type` that is an absolute `http(s)` URL — a `javascript:` in the preferred
slot costs nothing, it does not suppress the other — and otherwise to this page, which is the error
index. It never synthesizes a **per-code** URL for a code no row here documents: there is one docs
URL in the framework, `ERROR_DOCS_URL`, and a code lives here in a table row, which has no anchor to
link at. `As of 2026-08-23`.

## Queries and live queries

| Code | Means |
|---|---|
| [`X_QUERY_DUPLICATE`](/errors/X_QUERY_DUPLICATE) | two queries registered under one name |
| [`X_QUERY_FOREIGN`](/errors/X_QUERY_FOREIGN) | a value that is not a query was projected as one |
| [`X_QUERY_UNREGISTERED`](/errors/X_QUERY_UNREGISTERED) | a query was projected before it was registered |
| [`X_MATCHER_UNSUPPORTED`](/errors/X_MATCHER_UNSUPPORTED) | the live matcher cannot evaluate this SQL incrementally |
| [`X_QUERY_DEPRECATION_INVALID`](/errors/X_QUERY_DEPRECATION_INVALID) | a query declares a deprecation whose dates cannot be rendered |
| [`X_QUERY_SINGLE_INVALID`](/errors/X_QUERY_SINGLE_INVALID) | a query declares single: as something other than a boolean |
| [`X_QUERY_AUDIT_SINK_MISSING`](/errors/X_QUERY_AUDIT_SINK_MISSING) | a query declares audit: true and no audit sink is installed |
| [`X_QUERY_AUDIT_SINK_FAILED`](/errors/X_QUERY_AUDIT_SINK_FAILED) | an audited read was refused because the audit sink rejected its record |
| [`X_QUERY_DOWNLOAD_INVALID`](/errors/X_QUERY_DOWNLOAD_INVALID) | a query declares a download it cannot serve |
| [`X_QUERY_DOWNLOAD_ONLY`](/errors/X_QUERY_DOWNLOAD_ONLY) | rows were asked of a query that answers a file |
| [`X_QUERY_DOWNLOAD_TOKEN_INVALID`](/errors/X_QUERY_DOWNLOAD_TOKEN_INVALID) | a download URL carries a token this app did not mint for it |
| [`X_QUERY_DOWNLOAD_TOKEN_EXPIRED`](/errors/X_QUERY_DOWNLOAD_TOKEN_EXPIRED) | a download URL is past its expiry |
| [`X_QUERY_HTTP_PATH_INVALID`](/errors/X_QUERY_HTTP_PATH_INVALID) | a query's pinned http.path is not a valid path template |
| [`X_QUERY_ETAG_INVALID`](/errors/X_QUERY_ETAG_INVALID) | etag: true on a read that has its own validator |
| [`X_QUERY_TIMEOUT_INVALID`](/errors/X_QUERY_TIMEOUT_INVALID) | a read declares a timeoutMs that is not a whole positive number of ms |
| [`X_QUERY_MAX_PAGE_INVALID`](/errors/X_QUERY_MAX_PAGE_INVALID) | a query declares a maxPage no page bound can hold |

## Jobs

| Code | Means |
|---|---|
| [`X_IDEMPOTENCY_REQUIRED`](/errors/X_IDEMPOTENCY_REQUIRED) | the job has no `idempotencyKey` |
| [`X_JOB_TENANT_REQUIRED`](/errors/X_JOB_TENANT_REQUIRED) | the job declares no tenant |
| [`X_JOB_DUPLICATE`](/errors/X_JOB_DUPLICATE) | a name or a live key already has a job |
| [`X_STEP_DUPLICATE`](/errors/X_STEP_DUPLICATE) | two `step.run` calls share a name |
| [`X_JOB_MAX_ATTEMPTS`](/errors/X_JOB_MAX_ATTEMPTS) | the job exhausted its retries |
| [`X_JOB_TIMEOUT`](/errors/X_JOB_TIMEOUT) | a job exceeded its wall-clock limit |
| [`X_JOB_ROW_STATUS_UNKNOWN`](/errors/X_JOB_ROW_STATUS_UNKNOWN) | a queue row carries a status this build does not know |
| [`X_JOB_CLAIM_QUEUES_EMPTY`](/errors/X_JOB_CLAIM_QUEUES_EMPTY) | a driver was asked to claim with `queues: []` |
| [`X_ACTION_JOB_UNBRIDGED`](/errors/X_ACTION_JOB_UNBRIDGED) | an action projection was registered as a job |
| [`X_JOB_CONCURRENCY_UNENFORCEABLE`](/errors/X_JOB_CONCURRENCY_UNENFORCEABLE) | `job.concurrency` is declared and cannot be enforced |
| [`X_JOB_LEASE_LOST`](/errors/X_JOB_LEASE_LOST) | the queue took this job back mid-run |
| [`X_JOB_SLOT_LOST`](/errors/X_JOB_SLOT_LOST) | the fleet concurrency slot this run held was taken by another worker |
| [`X_JOB_NOT_CANCELLABLE`](/errors/X_JOB_NOT_CANCELLABLE) | the job cannot be cancelled |
| [`X_OUTBOX_NO_TX`](/errors/X_OUTBOX_NO_TX) | enqueue outside a transaction |
| [`X_DRIVER_UNAVAILABLE`](/errors/X_DRIVER_UNAVAILABLE) | the queue driver is unreachable |
| [`X_JOB_DECLARATION_INVALID`](/errors/X_JOB_DECLARATION_INVALID) | the job declaration is missing or mis-declares a field |
| [`X_JOB_NOT_REQUEUEABLE`](/errors/X_JOB_NOT_REQUEUEABLE) | the job is still live and cannot be requeued |
| [`X_JOB_KEY_BUSY`](/errors/X_JOB_KEY_BUSY) | the concurrency key already holds its limit of runs |
| [`X_JOB_NOT_REMOVABLE`](/errors/X_JOB_NOT_REMOVABLE) | the job is running and cannot be removed |
| [`X_JOB_NOT_PROMOTABLE`](/errors/X_JOB_NOT_PROMOTABLE) | the job is not waiting on its run time |
| [`X_JOB_PAGE_INVALID`](/errors/X_JOB_PAGE_INVALID) | a job list page was asked for outside its bounds |
| [`X_JOB_ON_SETTLED_FAILED`](/errors/X_JOB_ON_SETTLED_FAILED) | the onSettled hook failed after the run was settled |
| [`X_JOB_NOT_FOUND`](/errors/X_JOB_NOT_FOUND) | the queue holds no job with this id |
| [`X_JOB_TENANT_MISMATCH`](/errors/X_JOB_TENANT_MISMATCH) | a job's payload names an org other than the tenant it runs under |
| [`X_STEP_OUTPUT_UNSERIALIZABLE`](/errors/X_STEP_OUTPUT_UNSERIALIZABLE) | a step returned a value JSON cannot hold |
| [`X_JOB_EVENT_INVALID`](/errors/X_JOB_EVENT_INVALID) | a waited event failed its schema |
| [`X_IMPORT_HEADER_MISMATCH`](/errors/X_IMPORT_HEADER_MISMATCH) | the csv header does not name the declared columns |
| [`X_IMPORT_RECORD_TOO_LARGE`](/errors/X_IMPORT_RECORD_TOO_LARGE) | one record runs past the bytes a record may hold |
| [`X_IMPORT_TOO_MANY_ERRORS`](/errors/X_IMPORT_TOO_MANY_ERRORS) | more rows were rejected than the import allows |
| [`X_JOB_ENQUEUE_BATCH_TOO_LARGE`](/errors/X_JOB_ENQUEUE_BATCH_TOO_LARGE) | enqueueMany was handed more inputs than one call may stage |
| [`X_WEBHOOK_RECEIVER_INVALID`](/errors/X_WEBHOOK_RECEIVER_INVALID) | a webhookReceiver() declaration cannot be served |
| [`X_WEBHOOK_RECEIVER_UNAVAILABLE`](/errors/X_WEBHOOK_RECEIVER_UNAVAILABLE) | an inbound webhook could not be queued, so it was not acknowledged |
| [`X_WEBHOOK_EVENT_ID_INVALID`](/errors/X_WEBHOOK_EVENT_ID_INVALID) | the event id a webhook receiver verified is not one it can key a job by |
| [`X_JOB_COMPENSATION_FAILED`](/errors/X_JOB_COMPENSATION_FAILED) | a compensator could not undo its step |
| [`X_STEP_OUTCOME_UNKNOWN`](/errors/X_STEP_OUTCOME_UNKNOWN) | a once step started and never completed |
| [`X_CONSUMER_INVALID`](/errors/X_CONSUMER_INVALID) | a consumer() declaration cannot be run as declared |
| [`X_CONSUMER_SELF_ENQUEUE`](/errors/X_CONSUMER_SELF_ENQUEUE) | a consumer enqueued itself from inside its own run |
| [`X_BACKFILL_SOURCE_INVALID`](/errors/X_BACKFILL_SOURCE_INVALID) | a backfill() declares both or neither of source and pages, or input with no scope |
| [`X_STEP_NOT_RESOLVABLE`](/errors/X_STEP_NOT_RESOLVABLE) | the step is not an unknown once outcome an operator can resolve |
| [`X_JOB_ROLLUP_INVALID`](/errors/X_JOB_ROLLUP_INVALID) | a rollup declaration cannot be run |
| [`X_JOB_REFRESH_VIEW_INVALID`](/errors/X_JOB_REFRESH_VIEW_INVALID) | a refreshView declaration names no materialized view it can refresh |
| [`X_SUBJECT_TABLE_UNDECLARED`](/errors/X_SUBJECT_TABLE_UNDECLARED) | a table reaches the declared subject and defineSubject gives it no treatment |
| [`X_SUBJECT_TREATMENT_INVALID`](/errors/X_SUBJECT_TREATMENT_INVALID) | a defineSubject treatment cannot be carried out |
| [`X_SUBJECT_CYCLE`](/errors/X_SUBJECT_CYCLE) | the subject erase has no deletion order |
| [`X_LOCK_NOT_ACQUIRED`](/errors/X_LOCK_NOT_ACQUIRED) | withLock could not take the lock within its wait bound |
| [`X_LOCK_LOST`](/errors/X_LOCK_LOST) | a lock withLock held expired before its work finished |
| [`X_LOCK_STORE_MISSING`](/errors/X_LOCK_STORE_MISSING) | withLock found no lease store to hold the lock in |
| [`X_LEDGER_UNBALANCED`](/errors/X_LEDGER_UNBALANCED) | a ledger posting does not sum to zero in every currency |
| [`X_LEDGER_ENTRY_INVALID`](/errors/X_LEDGER_ENTRY_INVALID) | a ledger entry is not a whole-minor Money amount on a named account |
| [`X_PERSONAL_DATA_UNERASED`](/errors/X_PERSONAL_DATA_UNERASED) | a subject erase would leave a personalData() column of a reached table |
| [`X_PERSONAL_DATA_UNREACHED`](/errors/X_PERSONAL_DATA_UNREACHED) | an entity carries personalData() columns no declared subject reaches |
| [`X_LEDGER_POSTING_CONFLICT`](/errors/X_LEDGER_POSTING_CONFLICT) | a ledger posting key is already stored with other entries |

### Backfills

Seven codes because each sends the reader somewhere different. Full walkthrough: [Migrations and backfills](/migrations-and-backfills#errors).

| Code | Means |
|---|---|
| [`X_BACKFILL_PENDING`](/errors/X_BACKFILL_PENDING) | a declared backfill has never completed |
| [`X_BACKFILL_APPLIED`](/errors/X_BACKFILL_APPLIED) | the ledger already holds a completed pass |
| [`X_BACKFILL_ENVIRONMENT`](/errors/X_BACKFILL_ENVIRONMENT) | the backfill is not declared for this environment |
| [`X_BACKFILL_MIGRATION_PENDING`](/errors/X_BACKFILL_MIGRATION_PENDING) | the migration this backfill requires is not applied |
| [`X_BACKFILL_RUNNING`](/errors/X_BACKFILL_RUNNING) | a pass under this name is already live |
| [`X_BACKFILL_STALLED`](/errors/X_BACKFILL_STALLED) | the sweep ended with rows its own count still matches |
| [`X_BACKFILL_UNKNOWN`](/errors/X_BACKFILL_UNKNOWN) | no declaration carries this backfill name |

### Outbound webhooks

`webhook()` is a job factory, so a delivery ends on one of these eight — every one thrown inside a worker, where `ROLE=worker` opens no HTTP port, so none of them ever answers a request. The INBOUND pair is `X_WEBHOOK_SIGNATURE_INVALID` and `X_WEBHOOK_SIGNATURE_STALE` under [HTTP](#http), and both are 401.

The retry classification is what the split is for, and all eight are **listed** in `registerErrorRetry` rather than left to the default: `classifyThrown` reads an unregistered code as UNCLASSIFIED, which spends a delivery's whole retry policy re-proving that a 404 endpoint is still a 404.

| Classification | Codes |
|---|---|
| `retryable` | `X_WEBHOOK_DELIVERY_FAILED` |
| `retry-after` | `X_WEBHOOK_DELIVERY_THROTTLED` |
| `terminal` | the other six |

No secret and no signature reaches a `cause`, a `fix` or a `meta`, and a URL is redacted to origin + path — several senders in the wild put a token in the query string, and all three fields reach the log store and the dead-letter row.

| Code | Means |
|---|---|
| [`X_WEBHOOK_ENDPOINT_UNKNOWN`](/errors/X_WEBHOOK_ENDPOINT_UNKNOWN) | no endpoint carries this id |
| [`X_WEBHOOK_ENDPOINT_INVALID`](/errors/X_WEBHOOK_ENDPOINT_INVALID) | the endpoint cannot be delivered to as declared |
| [`X_WEBHOOK_ENDPOINT_DISABLED`](/errors/X_WEBHOOK_ENDPOINT_DISABLED) | the endpoint takes no deliveries |
| [`X_WEBHOOK_EVENT_UNKNOWN`](/errors/X_WEBHOOK_EVENT_UNKNOWN) | no event carries this id |
| [`X_WEBHOOK_EVENT_INVALID`](/errors/X_WEBHOOK_EVENT_INVALID) | the event cannot be signed as declared |
| [`X_WEBHOOK_DELIVERY_FAILED`](/errors/X_WEBHOOK_DELIVERY_FAILED) | the endpoint did not accept the delivery |
| [`X_WEBHOOK_DELIVERY_THROTTLED`](/errors/X_WEBHOOK_DELIVERY_THROTTLED) | the endpoint asked for the delivery later, and said when |
| [`X_WEBHOOK_DELIVERY_REJECTED`](/errors/X_WEBHOOK_DELIVERY_REJECTED) | the endpoint refused the delivery in a way a retry cannot change |

### Exports

`exportRows()` is a job factory too, and both its codes refuse the DECLARATION rather than the data — the same `row()` over the same page answers the same way on every attempt, so both are `terminal`.

| Code | Means |
|---|---|
| [`X_EXPORT_ROW_INVALID`](/errors/X_EXPORT_ROW_INVALID) | `row()` answered something the declared columns do not carry |
| [`X_EXPORT_PART_TOO_LARGE`](/errors/X_EXPORT_PART_TOO_LARGE) | one page encoded to more bytes than a part may hold |

## Realtime

| Code | Means |
|---|---|
| [`X_SOCKET_UNAUTHENTICATED`](/errors/X_SOCKET_UNAUTHENTICATED) | the sync upgrade carried no credential this app accepts |
| [`X_SOCKET_AUTH_UNAVAILABLE`](/errors/X_SOCKET_AUTH_UNAVAILABLE) | the sync node could not decide who a connecting socket is |
| [`X_TOPIC_FORBIDDEN`](/errors/X_TOPIC_FORBIDDEN) | the actor may not subscribe to this topic |
| [`X_SUBSCRIPTION_LIMIT`](/errors/X_SUBSCRIPTION_LIMIT) | socket, actor, tenant or node hit its subscription cap |
| [`X_FRAME_RATE_LIMIT`](/errors/X_FRAME_RATE_LIMIT) | one socket sent frames faster than this node will route them |
| [`X_SUBSCRIPTION_ID_TAKEN`](/errors/X_SUBSCRIPTION_ID_TAKEN) | a subscribe frame reused a `sid` this socket already holds |
| [`X_PROTOCOL_VERSION`](/errors/X_PROTOCOL_VERSION) | client and sync node disagree on the wire protocol |
| [`X_CURSOR_STALE`](/errors/X_CURSOR_STALE) | the resume LSN is outside the change buffer |
| [`X_REBASE_CONFLICT`](/errors/X_REBASE_CONFLICT) | a local mutation could not be rebased |
| [`X_TRANSPORT_UNAVAILABLE`](/errors/X_TRANSPORT_UNAVAILABLE) | the fanout bus is unreachable |
| [`X_TRANSPORT_PROTOCOL`](/errors/X_TRANSPORT_PROTOCOL) | the bus does not speak the protocol this build speaks |
| [`X_REPLICATION_FAILED`](/errors/X_REPLICATION_FAILED) | the replication connection was refused |
| [`X_REPLICATION_PROTOCOL`](/errors/X_REPLICATION_PROTOCOL) | the WAL stream cannot be decoded |
| [`X_REPLICATOR_SLOT_HELD`](/errors/X_REPLICATOR_SLOT_HELD) | another replicator already owns this database |
| [`X_LIVE_CLIENT_MISSING`](/errors/X_LIVE_CLIENT_MISSING) | retired in 21.0.0 (no LiveClient to register; see X_REALTIME_UNINSTALLED): a realtime hook ran in a browser with no LiveClient registered |
| [`X_LIVE_SERVER_RENDER`](/errors/X_LIVE_SERVER_RENDER) | a browser-only live operation ran during a server render |
| [`X_QUERY_NOT_SUBSCRIBABLE`](/errors/X_QUERY_NOT_SUBSCRIBABLE) | retired in 21.0.0 (liveHookFor was deleted; useQuery reads any query): a hook was bound to a query that is not declared live |
| [`X_LIVE_ROW_UNIDENTIFIED`](/errors/X_LIVE_ROW_UNIDENTIFIED) | a live query returned a row with no id |
| [`X_LIVE_REPLICA_IDENTITY`](/errors/X_LIVE_REPLICA_IDENTITY) | a replicated table has no replica identity |
| [`X_LIVE_QUERY_UNKNOWN`](/errors/X_LIVE_QUERY_UNKNOWN) | no live query is registered under the name a `subscribe` frame asked for |
| [`X_REALTIME_UNINSTALLED`](/errors/X_REALTIME_UNINSTALLED) | a realtime hook ran in an island bundle that never installed realtime |
| [`X_SYNC_UNCONFIGURED`](/errors/X_SYNC_UNCONFIGURED) | a live hook needed the page socket and no sync target was configured |
| [`X_RECORD_REJECTED`](/errors/X_RECORD_REJECTED) | a row reached the record store in a shape it cannot hold |
| [`X_LOCAL_STORE_UNAVAILABLE`](/errors/X_LOCAL_STORE_UNAVAILABLE) | the page's durable store could not open |
| [`X_CHANNEL_DECLARATION_INVALID`](/errors/X_CHANNEL_DECLARATION_INVALID) | a channel() declaration cannot route its rows |
| [`X_REALTIME_TOPOLOGY`](/errors/X_REALTIME_TOPOLOGY) | a sync node boots on a real database with no reachable change feed |
| [`X_REPLICATION_TLS`](/errors/X_REPLICATION_TLS) | the replication connection failed TLS |
| [`X_SOCKET_ORIGIN_REFUSED`](/errors/X_SOCKET_ORIGIN_REFUSED) | the websocket upgrade came from another origin |
| [`X_OFFLINE_QUEUE_ABANDONED`](/errors/X_OFFLINE_QUEUE_ABANDONED) | a write was queued after its page changed principal |
| [`X_SOCKET_LIMIT`](/errors/X_SOCKET_LIMIT) | one principal holds too many sockets on this node |
| [`X_REALTIME_PRODUCER_CONFLICT`](/errors/X_REALTIME_PRODUCER_CONFLICT) | two kinds of producer carry one table on the change bus |
| [`X_MUTATION_PATH_UNFILLED`](/errors/X_MUTATION_PATH_UNFILLED) | a pinned action's :param had no value in the write's input |
| [`X_DEVICE_OFFLINE`](/errors/X_DEVICE_OFFLINE) | no socket is open for the device a request addressed |
| [`X_DEVICE_REQUEST_TIMEOUT`](/errors/X_DEVICE_REQUEST_TIMEOUT) | a device did not answer a request before its deadline |
| [`X_DEVICE_FRAME_TOO_LARGE`](/errors/X_DEVICE_FRAME_TOO_LARGE) | a device socket frame is over the framework frame limit |
| [`X_CHANNEL_CATCHUP_POLICY_MISMATCH`](/errors/X_CHANNEL_CATCHUP_POLICY_MISMATCH) | a channel's catch-up read decides with another policy |
| [`X_REPLICATION_SLOT_INVALIDATED`](/errors/X_REPLICATION_SLOT_INVALIDATED) | the replication slot was invalidated |
| [`X_REPLICATION_SLOT_RECREATED`](/errors/X_REPLICATION_SLOT_RECREATED) | the replication slot was recreated |
| [`X_OFFLINE_QUEUE_FULL`](/errors/X_OFFLINE_QUEUE_FULL) | the offline queue is full |

## Cache

| Code | Means |
|---|---|
| [`X_CACHE_TAG_UNKNOWN`](/errors/X_CACHE_TAG_UNKNOWN) | a tag no entity declared |
| [`X_CACHE_TOO_LARGE`](/errors/X_CACHE_TOO_LARGE) | one entry exceeds the tier's byte budget |
| [`X_CACHE_DRIVER_UNAVAILABLE`](/errors/X_CACHE_DRIVER_UNAVAILABLE) | a tier's backing store is missing |
| [`X_CACHE_TTL_INVALID`](/errors/X_CACHE_TTL_INVALID) | a cache TTL that is not a positive number of milliseconds |
| [`X_CACHE_LIMIT_INVALID`](/errors/X_CACHE_LIMIT_INVALID) | a tier is given a numeric limit outside the domain its option accepts, refused at **construction**. Three domains, and the refusal names which: a **capacity** (`maxEntries`, `maxBytes`) is a whole number greater than zero; a **duration** (`defaultTtlMs`, `loadDeadlineMs`, a driver's request budget) is a whole number of milliseconds greater than zero; a **similarity floor** is a number from 0 to 1. So finite zero, a negative, a fraction and an unsafe integer are all refused too — not only `NaN` and `Infinity` |
| [`X_CACHE_JITTER_INVALID`](/errors/X_CACHE_JITTER_INVALID) | a TTL jitter fraction outside `[0, 1)` |
| [`X_CACHE_PURGE_FAILED`](/errors/X_CACHE_PURGE_FAILED) | the CDN refused a purge |
| [`X_CACHE_VALUE_UNENCODABLE`](/errors/X_CACHE_VALUE_UNENCODABLE) | a cached value the cache codec cannot encode |

## Storage

| Code | Means |
|---|---|
| [`X_STORAGE_CHECKSUM_MISMATCH`](/errors/X_STORAGE_CHECKSUM_MISMATCH) | bytes do not match the declared checksum |
| [`X_STORAGE_DELETE_FAILED`](/errors/X_STORAGE_DELETE_FAILED) | the object could not be deleted |
| [`X_STORAGE_LIST_FAILED`](/errors/X_STORAGE_LIST_FAILED) | the objects could not be listed |
| [`X_STORAGE_QUARANTINED`](/errors/X_STORAGE_QUARANTINED) | the object is still in quarantine |
| [`X_STORAGE_DISK_UNKNOWN`](/errors/X_STORAGE_DISK_UNKNOWN) | no disk with that name is configured |
| [`X_STORAGE_NOT_FOUND`](/errors/X_STORAGE_NOT_FOUND) | no object at that key |
| [`X_STORAGE_PATH_UNSAFE`](/errors/X_STORAGE_PATH_UNSAFE) | object key escapes its prefix |
| [`X_STORAGE_TOO_LARGE`](/errors/X_STORAGE_TOO_LARGE) | payload exceeds the upload size limit |
| [`X_STORAGE_TYPE_REJECTED`](/errors/X_STORAGE_TYPE_REJECTED) | content type is not allowed for this upload |
| [`X_STORAGE_URL_INVALID`](/errors/X_STORAGE_URL_INVALID) | signed URL does not match its signature |
| [`X_STORAGE_URL_UNVERIFIABLE`](/errors/X_STORAGE_URL_UNVERIFIABLE) | nothing can check the signature — no verifier was supplied |
| [`X_STORAGE_URL_EXPIRED`](/errors/X_STORAGE_URL_EXPIRED) | signed URL is past its expiry |
| [`X_STORAGE_ORG_MISMATCH`](/errors/X_STORAGE_ORG_MISMATCH) | object key belongs to another org |
| [`X_STORAGE_UPLOAD_FAILED`](/errors/X_STORAGE_UPLOAD_FAILED) | the signed upload was refused |
| [`X_STORAGE_SECRET_DEV`](/errors/X_STORAGE_SECRET_DEV) | upload grants would be signed with the shipped development key |
| [`X_STORAGE_NOT_PENDING`](/errors/X_STORAGE_NOT_PENDING) | the key is not a pending upload |
| [`X_STORAGE_KEY_CONFLICT`](/errors/X_STORAGE_KEY_CONFLICT) | the key collides with another key on a local or memory disk |
| [`X_STORAGE_PUT_FAILED`](/errors/X_STORAGE_PUT_FAILED) | the object could not be written |
| [`X_STORAGE_READ_FAILED`](/errors/X_STORAGE_READ_FAILED) | the object could not be read |
| [`X_STORAGE_OBJECT_LOCKED`](/errors/X_STORAGE_OBJECT_LOCKED) | the object is under retention or a legal hold |
| [`X_STORAGE_KEY_UNSHARED`](/errors/X_STORAGE_KEY_UNSHARED) | object key is outside every tenant and every shared prefix |
| [`X_STORAGE_ALREADY_PROMOTED`](/errors/X_STORAGE_ALREADY_PROMOTED) | the upload was already promoted onto its row |
| [`X_STORAGE_RANGE_UNSATISFIABLE`](/errors/X_STORAGE_RANGE_UNSATISFIABLE) | the requested byte range starts past the end of the object |
| [`X_STORAGE_OBJECT_CHANGED`](/errors/X_STORAGE_OBJECT_CHANGED) | the object changed while it was being promoted |
| [`X_STORAGE_UPLOAD_SIZE_UNDECLARED`](/errors/X_STORAGE_UPLOAD_SIZE_UNDECLARED) | an upload grant was asked for without the size of the file |
| [`X_STORAGE_WRITE_OUTCOME_UNKNOWN`](/errors/X_STORAGE_WRITE_OUTCOME_UNKNOWN) | a write was sent and its answer lost, and the disk could not say whether it landed |
| [`X_STORAGE_MULTIPART_UNSUPPORTED`](/errors/X_STORAGE_MULTIPART_UNSUPPORTED) | this disk cannot take an upload in parts |
| [`X_STORAGE_UPLOAD_UNKNOWN`](/errors/X_STORAGE_UPLOAD_UNKNOWN) | no open multipart upload has that id |
| [`X_STORAGE_PARTS_INVALID`](/errors/X_STORAGE_PARTS_INVALID) | the parts named do not match the parts stored |
| [`X_STORAGE_UPLOAD_INFECTED`](/errors/X_STORAGE_UPLOAD_INFECTED) | the upload scanner found malware in the file |
| [`X_STORAGE_SCAN_UNAVAILABLE`](/errors/X_STORAGE_SCAN_UNAVAILABLE) | the upload scanner could not give a verdict |
| [`X_STORAGE_TARGET_UNSCANNED`](/errors/X_STORAGE_TARGET_UNSCANNED) | a targeted upload grant would bypass the upload scanner |

## Flags

`X_FLAG_EXPIRED` is the only code in the framework that is **reported and never thrown**: an overdue temporary flag is a debt, not an outage, so `isEnabled()` hands it to the configured `ErrorReporter` as a `warning` (rate-limited to one report per key per hour) and still answers its targeting. Everything else here fails at declaration time.

| Code | Means |
|---|---|
| [`X_FLAG_DUPLICATE`](/errors/X_FLAG_DUPLICATE) | two flags were declared with the same key |
| [`X_FLAG_EXPIRED`](/errors/X_FLAG_EXPIRED) | a temporary flag is past its expiry and is still being evaluated |
| [`X_FLAG_EXPIRY_INVALID`](/errors/X_FLAG_EXPIRY_INVALID) | a temporary flag has no usable expiry date |
| [`X_FLAG_SUBJECT_REQUIRED`](/errors/X_FLAG_SUBJECT_REQUIRED) | a flag decides by a subject the evaluation context does not carry |
| [`X_FLAG_TARGETING_INVALID`](/errors/X_FLAG_TARGETING_INVALID) | flag targeting is out of range or malformed |
| [`X_FLAG_UNKNOWN`](/errors/X_FLAG_UNKNOWN) | no flag is declared under this key |

## Routes, render and budgets

| Code | Means |
|---|---|
| [`X_ROUTE_MODE_INVALID`](/errors/X_ROUTE_MODE_INVALID) | render mode not allowed on this surface, or not a render mode at all |
| [`X_ROUTE_OFFLINE_MISSING`](/errors/X_ROUTE_OFFLINE_MISSING) | the route's offline strategy is missing or contradictory |
| [`X_ROUTE_META_MISSING`](/errors/X_ROUTE_META_MISSING) | required metadata missing |
| [`X_ROUTE_UNNORMALIZED`](/errors/X_ROUTE_UNNORMALIZED) | a route was registered without `defineRoute` |
| [`X_ROUTE_DUPLICATE`](/errors/X_ROUTE_DUPLICATE) | two route files resolve to one URL |
| [`X_ROUTE_FILE_INVALID`](/errors/X_ROUTE_FILE_INVALID) | a route file is not named for its surface |
| [`X_STORAGE_UNWRITABLE`](/errors/X_STORAGE_UNWRITABLE) | the storage disk this process needs cannot be written to |
| [`X_ROUTE_LOAD_INVALID`](/errors/X_ROUTE_LOAD_INVALID) | a route declared a `load` that is not a function |
| [`X_ROUTE_LOAD_FAILED`](/errors/X_ROUTE_LOAD_FAILED) | a route's `load` threw while resolving its data |
| [`X_ROUTE_STATUS_INVALID`](/errors/X_ROUTE_STATUS_INVALID) | a route answered a status a rendered page cannot carry |
| [`X_SURFACE_BOUNDARY`](/errors/X_SURFACE_BOUNDARY) | a surface imported across the hard boundary |
| [`X_BOUNDARY_SITE_TO_APP`](/errors/X_BOUNDARY_SITE_TO_APP) | `site/` imported `app/` |
| [`X_BOUNDARY_APP_TO_API`](/errors/X_BOUNDARY_APP_TO_API) | `app/` imported `api/` at runtime |
| [`X_BOUNDARY_ROUTE_TO_DB`](/errors/X_BOUNDARY_ROUTE_TO_DB) | a route touched the database |
| [`X_BOUNDARY_SERVICE_TO_HTTP`](/errors/X_BOUNDARY_SERVICE_TO_HTTP) | a service imported HTTP |
| [`X_BOUNDARY_SHARED_LEAF`](/errors/X_BOUNDARY_SHARED_LEAF) | `shared/` imported a surface |
| [`X_ADMIN_FLATTENER_VIOLATION`](/errors/X_ADMIN_FLATTENER_VIOLATION) | a production `@ultimat3/admin` file read `$meta` or called `$describe()` directly |
| [`X_CONFIG_IMPORT_OUTSIDE_LOADER`](/errors/X_CONFIG_IMPORT_OUTSIDE_LOADER) | a file other than `packages/cli/src/app-config-load.ts` imports an app's `app.config.ts` |
| [`X_BUDGET_EXCEEDED`](/errors/X_BUDGET_EXCEEDED) | a route blew its JS budget |
| [`X_ISLAND_INVALID`](/errors/X_ISLAND_INVALID) | an island declaration cannot become a client entry |
| [`X_ISLAND_PROPS_INVALID`](/errors/X_ISLAND_PROPS_INVALID) | an island was handed props it may not receive |
| [`X_ISLAND_NOT_HYDRATED`](/errors/X_ISLAND_NOT_HYDRATED) | a page renders an island nothing would boot |
| [`X_BUDGET_UNMEASURED`](/errors/X_BUDGET_UNMEASURED) | a route declares a budget the build never measured |
| [`X_LIVE_ROUTE_NO_ISLAND`](/errors/X_LIVE_ROUTE_NO_ISLAND) | a route reads live rows and boots nothing that could receive them |
| [`X_PRERENDER_FAILED`](/errors/X_PRERENDER_FAILED) | a prerendered path threw during build |
| [`X_STYLES_GLOBAL_MISSING`](/errors/X_STYLES_GLOBAL_MISSING) | a surface renders documents whose CSS defines no `:root` custom properties |
| [`X_ASSET_MISSING`](/errors/X_ASSET_MISSING) | a page names a site asset the app does not have |
| [`X_ROUTE_POST_INVALID`](/errors/X_ROUTE_POST_INVALID) | a page route's post binding cannot be mounted |
| [`X_ROUTE_NAVIGATION_INVALID`](/errors/X_ROUTE_NAVIGATION_INVALID) | a route's navigation is not 'prefetch', 'document', 'modal' or { modal: true, prefetch: 'intent' }, or its surface has no client navigation |
| [`X_NAVIGATION_MODAL_PATH_INVALID`](/errors/X_NAVIGATION_MODAL_PATH_INVALID) | openModal was given something that is not a path of this origin |

## SEO

| Code | Means |
|---|---|
| [`X_SEO_META_MISSING`](/errors/X_SEO_META_MISSING) | a `site/` route is missing required metadata |
| [`X_SEO_META_TOO_LONG`](/errors/X_SEO_META_TOO_LONG) | title or description exceeds what results render |
| [`X_SEO_DUPLICATE_META`](/errors/X_SEO_DUPLICATE_META) | two routes share a title or description |
| [`X_SEO_CANONICAL_MISMATCH`](/errors/X_SEO_CANONICAL_MISMATCH) | canonical URL does not match the route path |
| [`X_LD_INVALID`](/errors/X_LD_INVALID) | JSON-LD node is missing a required schema.org field |
| [`X_SITEMAP_TOO_LARGE`](/errors/X_SITEMAP_TOO_LARGE) | sitemap exceeds the 50,000-entry limit |
| [`X_IMAGE_QUERY_INVALID`](/errors/X_IMAGE_QUERY_INVALID) | a minted image URL's `?w=`/`?q=` value is present but unusable |
| [`X_SEO_LINK_INVALID`](/errors/X_SEO_LINK_INVALID) | a route meta link is unsafe or would fetch nothing |
| [`X_SITEMAP_ENTRY_INVALID`](/errors/X_SITEMAP_ENTRY_INVALID) | a sitemap entry carries a lastmod or a locale the sitemap cannot write |
| [`X_SEO_LLMS_DESCRIPTION_MISSING`](/errors/X_SEO_LLMS_DESCRIPTION_MISSING) | a page listed in llms.txt has no description |
| [`X_SEO_OG_IMAGE_CONFLICT`](/errors/X_SEO_OG_IMAGE_CONFLICT) | a route meta og declares both image and capture |

## PWA and build skew

| Code | Means |
|---|---|
| [`X_PWA_NO_OFFLINE_FALLBACK`](/errors/X_PWA_NO_OFFLINE_FALLBACK) | `pwa.offline.fallback` is not set, or no route serves it |
| [`X_PWA_ICON_MISSING`](/errors/X_PWA_ICON_MISSING) | no source icon to generate from |
| [`X_PWA_MANIFEST_INVALID`](/errors/X_PWA_MANIFEST_INVALID) | the generated web manifest failed validation |
| [`X_SW_SCOPE_INVALID`](/errors/X_SW_SCOPE_INVALID) | the service-worker scope cannot serve the routes it precaches |
| [`X_BUILD_ID_MISSING`](/errors/X_BUILD_ID_MISSING) | no immutable build ID |
| [`X_PWA_STRATEGY_EXHAUSTED`](/errors/X_PWA_STRATEGY_EXHAUSTED) | a caching strategy had no cache, no network and no fallback |
| [`X_PWA_SYNC_FLUSH_FAILED`](/errors/X_PWA_SYNC_FLUSH_FAILED) | the background-sync outbox flush was rejected |
| [`X_PWA_SYNC_INCOMPLETE`](/errors/X_PWA_SYNC_INCOMPLETE) | the background-sync outbox flush left mutations queued |
| [`X_PWA_VAPID_KEY_MISSING`](/errors/X_PWA_VAPID_KEY_MISSING) | no VAPID key pair for push |
| [`X_PWA_VAPID_KEY_INVALID`](/errors/X_PWA_VAPID_KEY_INVALID) | the VAPID key pair is malformed or not a pair |
| [`X_PWA_PUSH_UNCONFIGURED`](/errors/X_PWA_PUSH_UNCONFIGURED) | push is not configured in this process |
| [`X_PWA_PUSH_FAILED`](/errors/X_PWA_PUSH_FAILED) | the push service did not accept the message, and may later |
| [`X_PWA_PUSH_REJECTED`](/errors/X_PWA_PUSH_REJECTED) | the push service refused the message and will refuse it again |
| [`X_PWA_PUSH_PAYLOAD_TOO_LARGE`](/errors/X_PWA_PUSH_PAYLOAD_TOO_LARGE) | the push message does not fit one 4096-byte record |
| [`X_PWA_PUSH_SUBSCRIPTION_INVALID`](/errors/X_PWA_PUSH_SUBSCRIPTION_INVALID) | the push subscription is not one a browser produced |
| [`X_PWA_PUSH_HOST_UNLISTED`](/errors/X_PWA_PUSH_HOST_UNLISTED) | the push endpoint is not on a push service this app sends to |

## i18n, money, time

| Code | Means |
|---|---|
| [`X_LOCALE_UNSUPPORTED`](/errors/X_LOCALE_UNSUPPORTED) | locale is not in the supported set |
| [`X_CATALOG_MISSING_KEYS`](/errors/X_CATALOG_MISSING_KEYS) | a catalog is missing keys used in source |
| [`X_CATALOG_UNREGISTERED`](/errors/X_CATALOG_UNREGISTERED) | a shipped catalog never reached the runtime registry |
| [`X_CATALOG_INVALID`](/errors/X_CATALOG_INVALID) | a catalog entry is malformed |
| [`X_CATALOG_SLOT_MISMATCH`](/errors/X_CATALOG_SLOT_MISMATCH) | two locales define one key with different interpolation slots |
| [`X_CATALOG_UNTRANSLATED`](/errors/X_CATALOG_UNTRANSLATED) | a locale still carries the reference locale's value |
| [`X_CURRENCY_UNKNOWN`](/errors/X_CURRENCY_UNKNOWN) | currency code not in the currency table |
| [`X_CURRENCY_MISMATCH`](/errors/X_CURRENCY_MISMATCH) | two `Money` values in different currencies |
| [`X_CURRENCY_INVALID`](/errors/X_CURRENCY_INVALID) | a `registerCurrency` declaration that cannot become a currency |
| [`X_CURRENCY_REDEFINED`](/errors/X_CURRENCY_REDEFINED) | one currency code registered twice with different meanings |
| [`X_MONEY_NOT_INTEGER`](/errors/X_MONEY_NOT_INTEGER) | a `Money.minor` that is not an integer |
| [`X_MONEY_SCALE_INVALID`](/errors/X_MONEY_SCALE_INVALID) | a `Money.scale` that is not usable — either the exponent itself, or the one two operands would have to meet at |
| [`X_ALLOCATION_INVALID`](/errors/X_ALLOCATION_INVALID) | split ratios or part count are unusable |
| [`X_RATE_MISSING`](/errors/X_RATE_MISSING) | no FX rate for the pair |
| [`X_TIMEZONE_INVALID`](/errors/X_TIMEZONE_INVALID) | not an IANA zone |
| [`X_INSTANT_INVALID`](/errors/X_INSTANT_INVALID) | not a parseable instant |
| [`X_DURATION_INVALID`](/errors/X_DURATION_INVALID) | not a parseable duration |
| [`X_CRON_INVALID`](/errors/X_CRON_INVALID) | not a parseable cron expression |
| [`X_SCHEDULE_INVALID`](/errors/X_SCHEDULE_INVALID) | a wall-clock field is out of range |
| [`X_DST_AMBIGUOUS`](/errors/X_DST_AMBIGUOUS) | the local time occurs twice |
| [`X_DST_NONEXISTENT`](/errors/X_DST_NONEXISTENT) | the local time does not exist |
| [`X_LOCALE_INVALID`](/errors/X_LOCALE_INVALID) | not a well-formed BCP 47 tag |
| [`X_CRON_NOT_DESCRIBABLE`](/errors/X_CRON_NOT_DESCRIBABLE) | a valid cron expression `describeCron` has no vocabulary for |
| [`X_MONEY_INPUT_INVALID`](/errors/X_MONEY_INPUT_INVALID) | a typed amount could not be read in this locale |
| [`X_I18N_FAMILY_INCOMPLETE`](/errors/X_I18N_FAMILY_INCOMPLETE) | a select or ordinal family has no _other |
| [`X_MONEY_NOT_DECIMAL`](/errors/X_MONEY_NOT_DECIMAL) | a fromDecimal input that is not a plain decimal string |

## Mail

| Code | Means |
|---|---|
| [`X_MAIL_LOCALE_MISSING`](/errors/X_MAIL_LOCALE_MISSING) | `send()` was called without a locale |
| [`X_MAIL_TEMPLATE_UNKNOWN`](/errors/X_MAIL_TEMPLATE_UNKNOWN) | no mail is registered under that id |
| [`X_MAIL_DUPLICATE`](/errors/X_MAIL_DUPLICATE) | two mails claim the same id |
| [`X_MAIL_ADDRESS_INVALID`](/errors/X_MAIL_ADDRESS_INVALID) | an envelope address could restructure the SMTP command line |
| [`X_MAIL_TEXT_MISSING`](/errors/X_MAIL_TEXT_MISSING) | the rendered mail has no plain-text part |
| [`X_MAIL_DRIVER_UNAVAILABLE`](/errors/X_MAIL_DRIVER_UNAVAILABLE) | no mail driver is configured |
| [`X_MAIL_CREDENTIAL_MISSING`](/errors/X_MAIL_CREDENTIAL_MISSING) | this deployment configured no mail transport |
| [`X_MAIL_HEADER_INVALID`](/errors/X_MAIL_HEADER_INVALID) | a header value carries a line break |
| [`X_MAIL_SEND_FAILED`](/errors/X_MAIL_SEND_FAILED) | the mail transport refused the message |
| [`X_MAIL_TRANSFORM_FAILED`](/errors/X_MAIL_TRANSFORM_FAILED) | the app mail transform threw or returned no message |
| [`X_MAIL_EVENT_UNVERIFIED`](/errors/X_MAIL_EVENT_UNVERIFIED) | a delivery notification is not signed by its provider |
| [`X_MAIL_EVENT_INVALID`](/errors/X_MAIL_EVENT_INVALID) | a delivery notification is not a shape this receiver reads |
| [`X_MAIL_EVENT_PROVIDER_UNREACHABLE`](/errors/X_MAIL_EVENT_PROVIDER_UNREACHABLE) | an SNS endpoint the receiver needed did not answer |
| [`X_MAIL_KEY_MISSING`](/errors/X_MAIL_KEY_MISSING) | a mail rendered a key or slot with no value in its locale |
| [`X_MAIL_PREVIEW_INVALID`](/errors/X_MAIL_PREVIEW_INVALID) | a mail's declared preview fails its own input schema |
| [`X_MAIL_PREVIEW_MISSING`](/errors/X_MAIL_PREVIEW_MISSING) | this mail declares no preview |

## Notifications

`notifier()` is a job factory — one queue row and one step trace for the whole fan-out, with every recipient a durable step. Five of the seven codes are the app's own DECLARATION, one is somebody else's server and one is another attempt of the same run, which is what decides the statuses: the five are 500, `X_NOTIFY_DELIVERY_FAILED` is **502** and `X_NOTIFY_DELIVERY_HELD` is **409**. That row is chosen for the day a notifier is invoked in a request rather than a job, and the asymmetry decides it — a wrong 502 costs nothing, and a wrong 500 pages the on-call for an email provider's outage, because `stages.ts` reports every `status >= 500` to the error monitor.

Three of them are raised at `notifier(...)`, while the app's modules load, so they fail the boot rather than a run: `X_NOTIFY_CHANNELS_EMPTY`, `X_NOTIFY_CHANNEL_DUPLICATE`, `X_NOTIFY_DIGEST_UNSUPPORTED`. The other four are raised inside the run.

| Code | Means |
|---|---|
| [`X_NOTIFY_CHANNELS_EMPTY`](/errors/X_NOTIFY_CHANNELS_EMPTY) | the notifier declares no channels |
| [`X_NOTIFY_CHANNEL_DUPLICATE`](/errors/X_NOTIFY_CHANNEL_DUPLICATE) | two deliveries share one channel name |
| [`X_NOTIFY_DIGEST_UNSUPPORTED`](/errors/X_NOTIFY_DIGEST_UNSUPPORTED) | a digest window is declared on a bulk channel |
| [`X_NOTIFY_FANOUT_TOO_WIDE`](/errors/X_NOTIFY_FANOUT_TOO_WIDE) | the audience is larger than one run may fan out to |
| [`X_NOTIFY_STORE_MISSING`](/errors/X_NOTIFY_STORE_MISSING) | a channel needs a store nothing installed |
| [`X_NOTIFY_DELIVERY_FAILED`](/errors/X_NOTIFY_DELIVERY_FAILED) | a channel did not accept the delivery |
| [`X_NOTIFY_DELIVERY_HELD`](/errors/X_NOTIFY_DELIVERY_HELD) | another attempt holds this delivery |
| [`X_NOTIFY_PUSH_DEVICE_GONE`](/errors/X_NOTIFY_PUSH_DEVICE_GONE) | the push provider says a device token is dead |
| [`X_NOTIFY_PUSH_PROVIDER_REFUSED`](/errors/X_NOTIFY_PUSH_PROVIDER_REFUSED) | APNs or FCM refused a push for good |
| [`X_NOTIFY_PUSH_MESSAGE_INVALID`](/errors/X_NOTIFY_PUSH_MESSAGE_INVALID) | a data-only push carries more than an id |
| [`X_NOTIFY_SMS_TRANSPORT_MISSING`](/errors/X_NOTIFY_SMS_TRANSPORT_MISSING) | an SMS was sent with no SmsTransport installed |
| [`X_NOTIFY_SMS_NUMBER_INVALID`](/errors/X_NOTIFY_SMS_NUMBER_INVALID) | an SMS number is not E.164 |

## MCP and AI

| Code | Means |
|---|---|
| [`X_UI_SHOT_ROUTE_UNKNOWN`](/errors/X_UI_SHOT_ROUTE_UNKNOWN) | a `ui.*` tool (`ui.shot`, `ui.inspect`, `ui.interact`) was asked for a path no route in this app answers |
| [`X_UI_SHOT_ROUTE_UNBUDGETED`](/errors/X_UI_SHOT_ROUTE_UNBUDGETED) | a `ui.*` tool (`ui.shot`, `ui.inspect`, `ui.interact`) refused a route that declares no `budget.js` |
| [`X_UI_INTERACT_STEPS_INVALID`](/errors/X_UI_INTERACT_STEPS_INVALID) | a `ui.interact` step list is over its bounds or malformed |
| [`X_UI_INTERACT_SECRET_FIELD`](/errors/X_UI_INTERACT_SECRET_FIELD) | `ui.interact` refused to type into a password field |
| [`X_UI_INTERACT_LEFT_APP`](/errors/X_UI_INTERACT_LEFT_APP) | a `ui.interact` step navigated off the dev server origin |
| [`X_UI_INTERACT_STEP_FAILED`](/errors/X_UI_INTERACT_STEP_FAILED) | a `ui.interact` step raised a scraping error |
| [`X_UI_DIFF_PATH_OUTSIDE`](/errors/X_UI_DIFF_PATH_OUTSIDE) | `ui.diff` was handed a path that does not resolve inside `.x/shot/` |
| [`X_UI_DIFF_FILE_MISSING`](/errors/X_UI_DIFF_FILE_MISSING) | `ui.diff` was handed a capture that is not on disk |
| [`X_UI_DIFF_SIZE_MISMATCH`](/errors/X_UI_DIFF_SIZE_MISMATCH) | `ui.diff` was handed two captures of different sizes |
| [`X_MCP_TOOL_UNKNOWN`](/errors/X_MCP_TOOL_UNKNOWN) | no such tool for this caller |
| [`X_MCP_ARGS_INVALID`](/errors/X_MCP_ARGS_INVALID) | tool arguments failed the input schema |
| [`X_MCP_SCOPE_DENIED`](/errors/X_MCP_SCOPE_DENIED) | the connection's token does not carry the tool's scope |
| [`X_MCP_QUERY_REJECTED`](/errors/X_MCP_QUERY_REJECTED) | `db.query` was not given one read-only statement |
| [`X_MCP_NOT_BRANCH_DB`](/errors/X_MCP_NOT_BRANCH_DB) | `db.migrate` was aimed at a database that is not a branch |
| [`X_MCP_PROTOCOL`](/errors/X_MCP_PROTOCOL) | the MCP handshake or auth is wrong |
| [`X_MCP_TOOL_UNDECLARED`](/errors/X_MCP_TOOL_UNDECLARED) | `defineAppMcp` lists a primitive that declares no MCP exposure |
| [`X_MCP_TOOL_UNSAFE`](/errors/X_MCP_TOOL_UNSAFE) | an MCP tool declares no policy |
| [`X_MCP_TOOL_DUPLICATE`](/errors/X_MCP_TOOL_DUPLICATE) | two primitives project to one MCP tool name |
| [`X_MCP_RESOURCE_DUPLICATE`](/errors/X_MCP_RESOURCE_DUPLICATE) | two resources claim one MCP resource URI |
| [`X_MCP_SCOPE_UNKNOWN`](/errors/X_MCP_SCOPE_UNKNOWN) | defineAppMcp scopes a tool this server does not project |
| [`X_MCP_SCOPE_CONFLICT`](/errors/X_MCP_SCOPE_CONFLICT) | two scopes claim one MCP tool |
| [`X_MCP_APP_UNMOUNTED`](/errors/X_MCP_APP_UNMOUNTED) | the app's MCP endpoint is exposed in config and nothing can be mounted |
| [`X_MCP_RATE_LIMITED`](/errors/X_MCP_RATE_LIMITED) | the caller has spent its allowance for this request's class |
| [`X_MCP_BODY_TOO_LARGE`](/errors/X_MCP_BODY_TOO_LARGE) | one MCP message is larger than the transport holds |
| [`X_AI_BUDGET_EXCEEDED`](/errors/X_AI_BUDGET_EXCEEDED) | a model call would exceed its budget |
| [`X_AI_GATEWAY_MISSING`](/errors/X_AI_GATEWAY_MISSING) | an `llm()` action ran with no gateway installed |
| [`X_AI_PROMPT_VERSION`](/errors/X_AI_PROMPT_VERSION) | prompt version or slots are wrong |
| [`X_AI_PROVIDER_UNAVAILABLE`](/errors/X_AI_PROVIDER_UNAVAILABLE) | the model provider is unreachable |
| [`X_AI_MODEL_UNKNOWN`](/errors/X_AI_MODEL_UNKNOWN) | a model id the app never registered (the framework registers none since 25.0.0) |
| [`X_AI_PROMPT_SECRET`](/errors/X_AI_PROMPT_SECRET) | a `Secret` was about to be rendered into a prompt |
| [`X_LLM_STREAM_INVALID`](/errors/X_LLM_STREAM_INVALID) | a streamed answer failed its output schema, and a stream cannot repair |
| [`X_AGENT_MAX_TURNS`](/errors/X_AGENT_MAX_TURNS) | an agent hit its turn ceiling without answering |
| [`X_AGENT_TOOL_UNEXPOSED`](/errors/X_AGENT_TOOL_UNEXPOSED) | an agent lists a tool that is neither in-process nor an MCP-exposed action |
| [`X_HIVE_EMPTY`](/errors/X_HIVE_EMPTY) | a `hive()` split into zero members, so the fan-out ran nothing |
| [`X_AI_KEY_MISSING`](/errors/X_AI_KEY_MISSING) | the provider API key is not set |
| [`X_AI_REQUEST_INVALID`](/errors/X_AI_REQUEST_INVALID) | the provider would reject this request |
| [`X_LLM_OUTPUT_INVALID`](/errors/X_LLM_OUTPUT_INVALID) | structured output failed its schema on the answer and on the repair turn |
| [`X_LLM_REFUSED`](/errors/X_LLM_REFUSED) | the model declined the request |
| [`X_LLM_TRUNCATED`](/errors/X_LLM_TRUNCATED) | the answer hit its `maxTokens` ceiling before it was complete |
| [`X_EVAL_THRESHOLD`](/errors/X_EVAL_THRESHOLD) | an eval scored below its tolerance |
| [`X_EVAL_BASELINE_MISSING`](/errors/X_EVAL_BASELINE_MISSING) | an eval has no recorded baseline to gate against |
| [`X_EVAL_BASELINE_INVALID`](/errors/X_EVAL_BASELINE_INVALID) | a recorded baseline cannot be read |
| [`X_EVAL_MISSING`](/errors/X_EVAL_MISSING) | a prompt has no eval |
| [`X_EVAL_RECORDING`](/errors/X_EVAL_RECORDING) | the gate ran with baseline recording switched on |
| [`X_VECTOR_DIM_MISMATCH`](/errors/X_VECTOR_DIM_MISMATCH) | embedding dimensions differ from the store |
| [`X_VECTOR_SCOPE_WIDENED`](/errors/X_VECTOR_SCOPE_WIDENED) | a derived vector scope tried to leave its tenant |
| [`X_AI_EMBEDDER_INVALID`](/errors/X_AI_EMBEDDER_INVALID) | an `Embedder` returned fewer vectors than texts it was given |
| [`X_MCP_GROUP_UNKNOWN`](/errors/X_MCP_GROUP_UNKNOWN) | defineAppMcp groups a tool this server does not project |
| [`X_MCP_GROUP_CONFLICT`](/errors/X_MCP_GROUP_CONFLICT) | two resource groups claim one MCP tool |
| [`X_MCP_SURFACE_INVALID`](/errors/X_MCP_SURFACE_INVALID) | the MCP meta surface is declared inconsistently |
| [`X_MCP_LIST_PARAMS_INVALID`](/errors/X_MCP_LIST_PARAMS_INVALID) | a tool's listParams names a key its own input does not accept |
| [`X_MCP_OAUTH_INVALID`](/errors/X_MCP_OAUTH_INVALID) | the MCP oauth block cannot be published as protected-resource metadata |
| [`X_MCP_IDEMPOTENCY_KEY_SHADOWED`](/errors/X_MCP_IDEMPOTENCY_KEY_SHADOWED) | an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key |
| [`X_MCP_SURFACE_OVER_BUDGET`](/errors/X_MCP_SURFACE_OVER_BUDGET) | an MCP surface an agent reads is larger than the app's budget for it |
| [`X_MCP_PATH_DUPLICATE`](/errors/X_MCP_PATH_DUPLICATE) | two MCP endpoints claim one path |
| [`X_VECTOR_UNSCOPED`](/errors/X_VECTOR_UNSCOPED) | a vector store was read with no tenant bound inside an org request |
| [`X_MCP_SCOPE_UNCOVERED`](/errors/X_MCP_SCOPE_UNCOVERED) | an MCP tool is covered by no scope in the scopes map |
| [`X_AI_CONTENT_UNSUPPORTED`](/errors/X_AI_CONTENT_UNSUPPORTED) | an image or document block the role, model or wire format cannot take |
| [`X_MCP_CONFIRMATION_PENDING`](/errors/X_MCP_CONFIRMATION_PENDING) | a gated MCP tool call waits for a person to approve it |
| [`X_MCP_CONFIRMATION_EXPIRED`](/errors/X_MCP_CONFIRMATION_EXPIRED) | an MCP confirmation expired before it was used or decided |
| [`X_MCP_CONFIRMATION_REJECTED`](/errors/X_MCP_CONFIRMATION_REJECTED) | a person rejected this MCP tool call |
| [`X_MCP_CONFIRMATION_DECIDED`](/errors/X_MCP_CONFIRMATION_DECIDED) | an MCP confirmation was already decided |
| [`X_MCP_CONFIRMATION_UNKNOWN`](/errors/X_MCP_CONFIRMATION_UNKNOWN) | no MCP confirmation has that id |
| [`X_MCP_CONFIRMATION_TOOL_UNKNOWN`](/errors/X_MCP_CONFIRMATION_TOOL_UNKNOWN) | mcpConfirmations gates a tool this server does not project |
| [`X_MCP_CONFIRMATION_CONTESTED`](/errors/X_MCP_CONFIRMATION_CONTESTED) | identical concurrent MCP calls kept racing one confirmation |
| [`X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH`](/errors/X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH) | an MCP confirmation approval did not carry the arguments the agent sent |
| [`X_AI_MODEL_UNRESOLVED`](/errors/X_AI_MODEL_UNRESOLVED) | a model call named no model |
| [`X_AGENT_TOOL_LOOP`](/errors/X_AGENT_TOOL_LOOP) | an agent repeated one tool call with one result and was stopped |
| [`X_AGENT_DEADLINE`](/errors/X_AGENT_DEADLINE) | an agent ran past its declared deadline and was stopped |
| [`X_LLM_TOOL_ARGUMENTS_INVALID`](/errors/X_LLM_TOOL_ARGUMENTS_INVALID) | a finished turn called a tool with arguments that are not JSON |
| [`X_AGENT_TRANSCRIPT_INVALID`](/errors/X_AGENT_TRANSCRIPT_INVALID) | an agent was asked to continue from a transcript it cannot read |
| [`X_AI_PROVIDER_UNEXPECTED`](/errors/X_AI_PROVIDER_UNEXPECTED) | a provider ended a turn with an unknown reason and an incomplete answer |
| [`X_MCP_EFFECT_UNDECLARED`](/errors/X_MCP_EFFECT_UNDECLARED) | an MCP tool on a meta-split surface declares no effect |
| [`X_MCP_EFFECT_CONFLICT`](/errors/X_MCP_EFFECT_CONFLICT) | a read-only MCP tool declares an effect |
| [`X_MCP_WRONG_TOOL`](/errors/X_MCP_WRONG_TOOL) | a meta-split action was called through the wrong dispatcher |
| [`X_MCP_USER_CONFIRMATION_REQUIRED`](/errors/X_MCP_USER_CONFIRMATION_REQUIRED) | a delete_resource commit did not carry confirmed_by_user: true |
| [`X_AGENT_TOOL_UNDECLARED`](/errors/X_AGENT_TOOL_UNDECLARED) | an agent run offered a tool its declaration does not list |
| [`X_AGENT_CONTEXT_EXHAUSTED`](/errors/X_AGENT_CONTEXT_EXHAUSTED) | an agent's next request would not fit its model's context window |
| [`X_AI_SCRIPT_EXHAUSTED`](/errors/X_AI_SCRIPT_EXHAUSTED) | a scriptedProvider was called more times than it has turns |
| [`X_MCP_PROTOCOL_UNSUPPORTED`](/errors/X_MCP_PROTOCOL_UNSUPPORTED) | the request names an MCP protocol version this server does not serve |
| [`X_MCP_HEADER_MISMATCH`](/errors/X_MCP_HEADER_MISMATCH) | an MCP request header is absent or disagrees with the body |
| [`X_MCP_ORIGIN_REFUSED`](/errors/X_MCP_ORIGIN_REFUSED) | an MCP request came from a browser page on another origin |
| [`X_EVAL_TOOL_UNDOUBLED`](/errors/X_EVAL_TOOL_UNDOUBLED) | an agent eval called a tool with no double |
| [`X_MCP_HOST_REFUSED`](/errors/X_MCP_HOST_REFUSED) | an MCP request named a Host that is not this machine |
| [`X_AI_CONTEXT_OVERFLOW`](/errors/X_AI_CONTEXT_OVERFLOW) | a provider refused a request as longer than the model context window |
| [`X_MCP_REMOTE_TOOL_CHANGED`](/errors/X_MCP_REMOTE_TOOL_CHANGED) | a remote MCP server's tool no longer matches tools.lock.json |
| [`X_MCP_REMOTE_REFUSED`](/errors/X_MCP_REMOTE_REFUSED) | a remote MCP server failed or refused the call |
| [`X_MCP_JOB_TOOL_INVALID`](/errors/X_MCP_JOB_TOOL_INVALID) | jobTool() was declared with something it cannot run |
| [`X_MCP_RECIPE_TOOL_UNKNOWN`](/errors/X_MCP_RECIPE_TOOL_UNKNOWN) | an MCP recipe step names a tool this server does not project |
| [`X_MCP_RECIPE_EXAMPLE_INVALID`](/errors/X_MCP_RECIPE_EXAMPLE_INVALID) | an MCP recipe step's example fails its tool's input |
| [`X_MCP_RECIPE_UNKNOWN`](/errors/X_MCP_RECIPE_UNKNOWN) | an error links to a docs://recipes/ URI no recipe serves |
| [`X_MCP_RECIPE_URI_RESERVED`](/errors/X_MCP_RECIPE_URI_RESERVED) | docs://recipes/ is owned by recipes: |
| [`X_MCP_REMOTE_AUTH_REQUIRED`](/errors/X_MCP_REMOTE_AUTH_REQUIRED) | a remote MCP server needs authorization this app does not hold |
| [`X_MCP_RECIPE_LINK_DANGLING`](/errors/X_MCP_RECIPE_LINK_DANGLING) | a recipe links to a docs://recipes/ URI no recipe serves |
| [`X_MCP_CONFIRMATION_QUORUM_PENDING`](/errors/X_MCP_CONFIRMATION_QUORUM_PENDING) | an MCP confirmation needs more approvers before the call runs |
| [`X_MCP_CONFIRMATION_EVIDENCE_INVALID`](/errors/X_MCP_CONFIRMATION_EVIDENCE_INVALID) | an MCP confirmation approval carries no valid signed evidence |
| [`X_MCP_CONFIRMATION_QUORUM_INVALID`](/errors/X_MCP_CONFIRMATION_QUORUM_INVALID) | mcpConfirmations approvers resolved a quorum no approver set can meet |
| [`X_MCP_CATALOG_TOOL_DUPLICATE`](/errors/X_MCP_CATALOG_TOOL_DUPLICATE) | a per-caller MCP catalog names one tool twice |
| [`X_MCP_CATALOG_UNRESOLVED`](/errors/X_MCP_CATALOG_UNRESOLVED) | a per-caller MCP catalog could not be resolved |
| [`X_MCP_TENANT_REQUIRED`](/errors/X_MCP_TENANT_REQUIRED) | an MCP call names no tenant |
| [`X_MCP_TENANT_UNRESOLVED`](/errors/X_MCP_TENANT_UNRESOLVED) | the tenant of an MCP call could not be resolved |
| [`X_MCP_TENANT_INVALID`](/errors/X_MCP_TENANT_INVALID) | defineAppMcp declares its tenant argument inconsistently |
| [`X_MCP_INCLUDE_EARLY`](/errors/X_MCP_INCLUDE_EARLY) | include: 'exposed' projected before the scan registered every exposed primitive |

## Scraping

`@ultimat3/scraping` owns its codes in `SCRAPE_OWNED_ERROR_CODES` and borrows two (`X_NOT_IMPLEMENTED`, `X_ENV_MISSING`) — the count is not written here because nothing derives it, and a number in prose beside a list that grows is a number that goes stale; `bun run manifest` re-derives the owner of every code. Every one is classified `retryable` or `terminal` **once**, in `SCRAPE_ERROR_RETRY` ([`packages/scraping/src/errors.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/scraping/src/errors.ts)), rather than re-decided by whichever `catch` saw it — a scraper's whole operational question is "was that the site being slow, or the site being different?"

The rule, stated once: **retryable means the same code, run again, has a real chance of a different answer.** Transport, budget and liveness faults qualify. Anything that says "the page is not the page this scraper was written against" does not — attempt 5 hammers a site with a request that cannot succeed, and on an authenticated target that is how three wrong attempts lock an account.

Two sets override the table, in `failures.ts`:

| Set | Codes | Effect |
|---|---|---|
| `NEVER_RETRIED` | `X_SCRAPE_AUTH_FAILED`, `X_SCRAPE_PROMPT_UNANSWERED` | no retry policy, backoff or recovery hook can reach them |
| `BURNS_SESSION` | `X_SCRAPE_BLOCKED`, `X_SCRAPE_SESSION_EXPIRED` | the persisted identity is discarded **before** the retry — a flagged profile stays flagged, so reloading it re-trips the same block every time |

| Code | Means |
|---|---|
| [`X_SCRAPE_DRIVER_UNKNOWN`](/errors/X_SCRAPE_DRIVER_UNKNOWN) | no browser driver is installed for this run |
| [`X_SCRAPE_CDP_ATTACH_FAILED`](/errors/X_SCRAPE_CDP_ATTACH_FAILED) | the CDP endpoint refused the attach |
| [`X_SCRAPE_BROWSER_UNREACHABLE`](/errors/X_SCRAPE_BROWSER_UNREACHABLE) | the browser went away mid-run |
| [`X_SCRAPE_BROWSER_MISSING`](/errors/X_SCRAPE_BROWSER_MISSING) | there is no browser on this machine for the driver to launch |
| [`X_SCRAPE_PROFILE_LOCKED`](/errors/X_SCRAPE_PROFILE_LOCKED) | another process holds this browser profile |
| [`X_SCRAPE_HOST_BLOCKED`](/errors/X_SCRAPE_HOST_BLOCKED) | the page asked for a host `allowHosts` does not list |
| [`X_SCRAPE_SELECTOR_MISSING`](/errors/X_SCRAPE_SELECTOR_MISSING) | the selector never appeared inside its window |
| [`X_SCRAPE_NOT_ACTIONABLE`](/errors/X_SCRAPE_NOT_ACTIONABLE) | the element is present and cannot be acted on |
| [`X_SCRAPE_TIMEOUT`](/errors/X_SCRAPE_TIMEOUT) | the step exceeded its wall-clock budget |
| [`X_SCRAPE_WEDGED`](/errors/X_SCRAPE_WEDGED) | the browser stopped answering and was killed |
| [`X_SCRAPE_WATCHDOG_STOPPED`](/errors/X_SCRAPE_WATCHDOG_STOPPED) | the wedge watchdog stopped measuring and the run was ended |
| [`X_SCRAPE_PAGE_CRASHED`](/errors/X_SCRAPE_PAGE_CRASHED) | the renderer process died |
| [`X_SCRAPE_OUTPUT_INVALID`](/errors/X_SCRAPE_OUTPUT_INVALID) | the extracted rows do not match the extract schema |
| [`X_SCRAPE_YIELD_COLLAPSED`](/errors/X_SCRAPE_YIELD_COLLAPSED) | the run succeeded and returned far too little |
| [`X_SCRAPE_YIELD_HISTORY_MISSING`](/errors/X_SCRAPE_YIELD_HISTORY_MISSING) | a `maxDrop` is declared and no history store can supply its baseline |
| [`X_SCRAPE_DOWNLOAD_TIMEOUT`](/errors/X_SCRAPE_DOWNLOAD_TIMEOUT) | the download never landed |
| [`X_SCRAPE_ROBOTS_DISALLOWED`](/errors/X_SCRAPE_ROBOTS_DISALLOWED) | `robots.txt` disallows this path |
| [`X_SCRAPE_FIXTURE_MISSING`](/errors/X_SCRAPE_FIXTURE_MISSING) | the fixture driver has no recording for this request |
| [`X_SCRAPE_FIXTURE_STALE`](/errors/X_SCRAPE_FIXTURE_STALE) | the recording is older than the fixture max age |
| [`X_SCRAPE_REMOTE_REQUIRED`](/errors/X_SCRAPE_REMOTE_REQUIRED) | this driver needs a `cdpUrl` and was given none |
| [`X_SCRAPE_RECOVER_REFUSED`](/errors/X_SCRAPE_RECOVER_REFUSED) | the recovery hook declined to recover this failure |
| [`X_SCRAPE_SECRET_EXPOSED`](/errors/X_SCRAPE_SECRET_EXPOSED) | an artifact would have carried a secret this run typed |
| [`X_SCRAPE_HTTP_FAILED`](/errors/X_SCRAPE_HTTP_FAILED) | the site answered the HTTP leg with a non-2xx status |
| [`X_SCRAPE_BODY_TOO_LARGE`](/errors/X_SCRAPE_BODY_TOO_LARGE) | the HTTP leg's response body ran past `maxBytes` |
| [`X_SCRAPE_REDIRECT_LOOP`](/errors/X_SCRAPE_REDIRECT_LOOP) | the HTTP leg followed its hop limit of redirects without an answer |
| [`X_SCRAPE_AUTH_FAILED`](/errors/X_SCRAPE_AUTH_FAILED) | the credentials were rejected |
| [`X_SCRAPE_SESSION_EXPIRED`](/errors/X_SCRAPE_SESSION_EXPIRED) | the restored session is no longer valid and nothing can renew it |
| [`X_SCRAPE_PROMPT_UNANSWERED`](/errors/X_SCRAPE_PROMPT_UNANSWERED) | a login step asked for a code and nothing answered |
| [`X_SCRAPE_CAPTURE_INVALID`](/errors/X_SCRAPE_CAPTURE_INVALID) | the capture names a framing no picture can be taken with |
| [`X_SCRAPE_BLOCKED`](/errors/X_SCRAPE_BLOCKED) | the site refused this client — the identity is spent |
| [`X_SCRAPE_KEY_INVALID`](/errors/X_SCRAPE_KEY_INVALID) | the key chord names no key a browser can press |
| [`X_SCRAPE_EGRESS_UNSUPPORTED`](/errors/X_SCRAPE_EGRESS_UNSUPPORTED) | this driver cannot give the session the exit the run asked for |
| [`X_SCRAPE_EGRESS_IN_PAYLOAD`](/errors/X_SCRAPE_EGRESS_IN_PAYLOAD) | the run exit carries a credential that is also in the job payload |
| [`X_SCRAPE_LAUNCH_ARGS_INVALID`](/errors/X_SCRAPE_LAUNCH_ARGS_INVALID) | the launch options carry arguments this driver cannot hand the browser |
| [`X_SCRAPE_PDF_OPTIONS_INVALID`](/errors/X_SCRAPE_PDF_OPTIONS_INVALID) | the PDF request names no single page size a print engine can lay out |
| [`X_SCRAPE_PDF_ORIGIN_MISSING`](/errors/X_SCRAPE_PDF_ORIGIN_MISSING) | pdf() has no origin to render the route on |
| [`X_SCRAPE_PDF_ROUTE_INVALID`](/errors/X_SCRAPE_PDF_ROUTE_INVALID) | a pdf() route is not a path on this app |
| [`X_SCRAPE_PDF_ROUTE_FAILED`](/errors/X_SCRAPE_PDF_ROUTE_FAILED) | the route pdf() printed answered an error status |
| [`X_CDP_BROWSER_MISSING`](/errors/X_CDP_BROWSER_MISSING) | no Chrome or Chromium is installed for the e2e driver to launch |
| [`X_CDP_LAUNCH_FAILED`](/errors/X_CDP_LAUNCH_FAILED) | the browser started and never announced a DevTools endpoint |
| [`X_CDP_CALL_FAILED`](/errors/X_CDP_CALL_FAILED) | the browser refused a DevTools call |
| [`X_CDP_TIMEOUT`](/errors/X_CDP_TIMEOUT) | a DevTools call did not answer inside its deadline |
| [`X_SCRAPE_PDF_BUSY`](/errors/X_SCRAPE_PDF_BUSY) | every pdf() render slot stayed busy past the queue deadline |

`X_NOT_IMPLEMENTED` and `X_ENV_MISSING` are `@ultimat3/core`'s and are documented above: the first is the honest stub the agent recovery seam throws, the second is what a declared secret with no value in the environment is — a missing environment variable, not a scraping concept needing its own code.

## Admin and manifest

| Code | Means |
|---|---|
| [`X_ADMIN_ENTITY_UNKNOWN`](/errors/X_ADMIN_ENTITY_UNKNOWN) | the admin references an entity that does not exist |
| [`X_ADMIN_POLICY_MISSING`](/errors/X_ADMIN_POLICY_MISSING) | an admin-exposed subject has no policy |
| [`X_ADMIN_FIELD_UNSUPPORTED`](/errors/X_ADMIN_FIELD_UNSUPPORTED) | a column type the admin cannot render |
| [`X_ADMIN_ACTION_DUPLICATE`](/errors/X_ADMIN_ACTION_DUPLICATE) | two registered admin actions carry one `name` |
| [`X_ADMIN_PAGE_UNGUARDED`](/errors/X_ADMIN_PAGE_UNGUARDED) | a custom admin page declared no permissions |
| [`X_ADMIN_PAGE_PATH_INVALID`](/errors/X_ADMIN_PAGE_PATH_INVALID) | a custom admin page has an unusable or already-taken path |
| [`X_ADMIN_DENIED`](/errors/X_ADMIN_DENIED) | the actor may not use this admin surface |
| [`X_ADMIN_TOOL_FORBIDDEN`](/errors/X_ADMIN_TOOL_FORBIDDEN) | an admin MCP tool was called without permission |
| [`X_ADMIN_INVALID`](/errors/X_ADMIN_INVALID) | an admin tool's arguments failed the resource schema |
| [`X_DEV_DASHBOARD_IN_PROD`](/errors/X_DEV_DASHBOARD_IN_PROD) | `/_x` was mounted outside dev |
| [`X_MANIFEST_DRIFT`](/errors/X_MANIFEST_DRIFT) | a committed manifest differs from the code |
| [`X_MANIFEST_STALE`](/errors/X_MANIFEST_STALE) | `openapi.json` is stale |
| [`X_MANIFEST_MISSING`](/errors/X_MANIFEST_MISSING) | the app ships no `x.manifest.json` at all |
| [`X_MANIFEST_BREAKING`](/errors/X_MANIFEST_BREAKING) | a published contract was removed or narrowed |
| [`X_AGENTS_MD_MISSING`](/errors/X_AGENTS_MD_MISSING) | no `AGENTS.md` |
| [`X_AGENTS_MD_TOO_LARGE`](/errors/X_AGENTS_MD_TOO_LARGE) | `AGENTS.md` grew past its cap |
| [`X_ADMIN_REPO_UNBOUND`](/errors/X_ADMIN_REPO_UNBOUND) | an admin resource has no database handle to read rows through |
| [`X_ADMIN_FILTER_INVALID`](/errors/X_ADMIN_FILTER_INVALID) | an admin list was asked for a filter, sort or scope its resource does not derive |
| [`X_ADMIN_ACTION_NOT_APPLICABLE`](/errors/X_ADMIN_ACTION_NOT_APPLICABLE) | an admin action was run on a row its when() rule excludes |
| [`X_ADMIN_MOUNT_MISSING`](/errors/X_ADMIN_MOUNT_MISSING) | an admin batch job ran in a process that never declared its admin |
| [`X_MANIFEST_FACT_INVALID`](/errors/X_MANIFEST_FACT_INVALID) | a manifest fact is a number JSON cannot write back |
| [`X_ADMIN_VIEW_WRITE`](/errors/X_ADMIN_VIEW_WRITE) | an admin resource over a view entity offers a write |
| [`X_ADMIN_READ_ONLY_WRITE`](/errors/X_ADMIN_READ_ONLY_WRITE) | an admin resource over a readOnly entity offers a write |

## Testing

| Code | Means |
|---|---|
| [`X_TEST_DB_UNAVAILABLE`](/errors/X_TEST_DB_UNAVAILABLE) | no Postgres for the test template |
| [`X_TEST_FIXTURE_UNAVAILABLE`](/errors/X_TEST_FIXTURE_UNAVAILABLE) | a declared fixture has no driver in this process |
| [`X_TEST_LIVE_NODE_UPGRADE_REFUSED`](/errors/X_TEST_LIVE_NODE_UPGRADE_REFUSED) | the in-process sync node refused the connection |
| [`X_TEST_LIVE_NODE_EMPTY`](/errors/X_TEST_LIVE_NODE_EMPTY) | the in-process sync node has no live query to serve |
| [`X_TEST_FIXTURE_UNKNOWN`](/errors/X_TEST_FIXTURE_UNKNOWN) | a test requested a fixture nobody registered |
| [`X_TEST_NETWORK_OFFLINE`](/errors/X_TEST_NETWORK_OFFLINE) | the test network is offline |
| [`X_TEST_NETWORK_SEALED`](/errors/X_TEST_NETWORK_SEALED) | a test tried to reach the network |
| [`X_TEST_NONDETERMINISTIC`](/errors/X_TEST_NONDETERMINISTIC) | a test read wall-clock time or unseeded randomness |
| [`X_TEST_EVAL_THRESHOLD`](/errors/X_TEST_EVAL_THRESHOLD) | an `evalTest()` score fell below its threshold |
| [`X_TEST_SCHEMA_EXPECTED`](/errors/X_TEST_SCHEMA_EXPECTED) | a matcher expected a Standard Schema and got something else |
| [`X_TEST_LOCATOR_EXPECTED`](/errors/X_TEST_LOCATOR_EXPECTED) | a matcher expected a locator and got something else |
| [`X_E2E_APP_FAILED`](/errors/X_E2E_APP_FAILED) | the app an e2e run spawned did not come up |
| [`X_E2E_EVALUATE_UNSUPPORTED`](/errors/X_E2E_EVALUATE_UNSUPPORTED) | a page.evaluate() closure cannot be sent into the browser |
| [`X_E2E_EVALUATE_CAPTURED`](/errors/X_E2E_EVALUATE_CAPTURED) | a page.evaluate() closure named a binding the page does not have |
| [`X_E2E_EVALUATE_THREW`](/errors/X_E2E_EVALUATE_THREW) | an expression an e2e page ran threw inside the browser |
| [`X_E2E_LOCATOR_EMPTY`](/errors/X_E2E_LOCATOR_EMPTY) | an e2e locator matched no element |
| [`X_E2E_LOCATOR_AMBIGUOUS`](/errors/X_E2E_LOCATOR_AMBIGUOUS) | an e2e locator matched more than one element and was asked to click |
| [`X_E2E_SERVICE_WORKER_ABSENT`](/errors/X_E2E_SERVICE_WORKER_ABSENT) | no service worker took control of the page within the budget |
| [`X_TEST_JOB_EXPECTED`](/errors/X_TEST_JOB_EXPECTED) | a matcher expected a job declaration and got something else |
| [`X_TEST_NETWORK_RACE`](/errors/X_TEST_NETWORK_RACE) | a request raced `unsealNetwork()` and lost the patched fetch |
| [`X_TEST_FACTORY_TRAIT_UNKNOWN`](/errors/X_TEST_FACTORY_TRAIT_UNKNOWN) | a factory was asked for a trait it does not declare |
| [`X_TEST_ISLAND_NOT_BUILT`](/errors/X_TEST_ISLAND_NOT_BUILT) | the island build produced no chunk for the file the test named |
| [`X_TEST_ISLAND_NO_MOUNT`](/errors/X_TEST_ISLAND_NO_MOUNT) | an island chunk exports no mount function |
| [`X_TEST_ISLAND_SELECTOR_UNSUPPORTED`](/errors/X_TEST_ISLAND_SELECTOR_UNSUPPORTED) | a selector is outside the island DOM's grammar |
| [`X_TEST_FACTORY_NOT_PERSISTED`](/errors/X_TEST_FACTORY_NOT_PERSISTED) | `create()` ran with no persister installed |
| [`X_TEST_REGISTRY_LEAK`](/errors/X_TEST_REGISTRY_LEAK) | a test file left a process-global registry dirty |
| [`X_SHOT_ISLAND_STATES_EMPTY`](/errors/X_SHOT_ISLAND_STATES_EMPTY) | a `*.island.states.ts` exports no `defineIslandStates` result |
| [`X_SHOT_ISLAND_UNPHOTOGRAPHABLE`](/errors/X_SHOT_ISLAND_UNPHOTOGRAPHABLE) | the island never reached a state worth photographing |
| [`X_SHOT_ISLAND_UNSTUBBED_REQUEST`](/errors/X_SHOT_ISLAND_UNSTUBBED_REQUEST) | the component requested something no state stub answers |
| [`X_SHOT_ISLAND_MISSING`](/errors/X_SHOT_ISLAND_MISSING) | a declared picture is not on disk when the run ends |
| [`X_TEST_ISLAND_STATES_EMPTY`](/errors/X_TEST_ISLAND_STATES_EMPTY) | an island state manifest declares no states |
| [`X_TEST_ISLAND_STATES_NOT_PURE`](/errors/X_TEST_ISLAND_STATES_NOT_PURE) | an island states file imports the component, a renderer or a sibling module |
| [`X_TEST_ISLAND_STATES_MISSING_FILE`](/errors/X_TEST_ISLAND_STATES_MISSING_FILE) | an island state manifest names an island that is not on disk |
| [`X_TEST_ISLAND_STATES_UNKNOWN`](/errors/X_TEST_ISLAND_STATES_UNKNOWN) | no island state manifest answers to that name |
| [`X_TEST_ISLAND_STATES_AMBIGUOUS`](/errors/X_TEST_ISLAND_STATES_AMBIGUOUS) | two island state manifests answer to one name |
| [`X_TEST_ISLAND_STATE_ID_INVALID`](/errors/X_TEST_ISLAND_STATE_ID_INVALID) | an island state id is not slug-shaped |
| [`X_TEST_ISLAND_STATE_DUPLICATE`](/errors/X_TEST_ISLAND_STATE_DUPLICATE) | two island states share one id |
| [`X_TEST_ISLAND_STATE_JSON_INVALID`](/errors/X_TEST_ISLAND_STATE_JSON_INVALID) | an island state carries a value JSON does not |
| [`X_TEST_ISLAND_STATE_CLOCK_INVALID`](/errors/X_TEST_ISLAND_STATE_CLOCK_INVALID) | an island state manifest pins a clock that is not pinnable |
| [`X_TEST_ISLAND_STATE_STUB_INVALID`](/errors/X_TEST_ISLAND_STATE_STUB_INVALID) | an island route stub is not `<METHOD> <pathname>` |
| [`X_TEST_POLICY_EXPECTED`](/errors/X_TEST_POLICY_EXPECTED) | a matcher expected a policy and got something else |
| [`X_TEST_OPENAPI_EXPECTED`](/errors/X_TEST_OPENAPI_EXPECTED) | a matcher expected an OpenAPI document and got something else |
| [`X_TEST_NUMBER_EXPECTED`](/errors/X_TEST_NUMBER_EXPECTED) | a matcher expected a finite number and got something else |
| [`X_TEST_ISLAND_STATE_UNKNOWN`](/errors/X_TEST_ISLAND_STATE_UNKNOWN) | an island state manifest declares no state with that id |
| [`X_TEST_APP_NOT_BOOTED`](/errors/X_TEST_APP_NOT_BOOTED) | describeApp handle read before boot |
| [`X_TEST_PACE_INVALID`](/errors/X_TEST_PACE_INVALID) | ULTIMATE_TEST_PACE is not a number at or above 1 |
| [`X_SEED_GRAPH_UNSATISFIED`](/errors/X_SEED_GRAPH_UNSATISFIED) | no generated row satisfies a table |
| [`X_E2E_A11Y_VIOLATION`](/errors/X_E2E_A11Y_VIOLATION) | a page fails the accessibility audit |
| [`X_SEED_GRAPH_ENTITY_UNKNOWN`](/errors/X_SEED_GRAPH_ENTITY_UNKNOWN) | a seed plan names an entity its writer was not given |
| [`X_TENANT_LEAK`](/errors/X_TENANT_LEAK) | another tenant's row reached a call's output or effect |
| [`X_TENANT_WRITE_CROSSED`](/errors/X_TENANT_WRITE_CROSSED) | a call by one tenant changed another tenant's row |
| [`X_JOB_CRASH_DIVERGED`](/errors/X_JOB_CRASH_DIVERGED) | a job run killed at a step boundary made an effect a different number of times than a clean run |
| [`X_JOB_SIM_INVARIANT`](/errors/X_JOB_SIM_INVARIANT) | a simulateJobs seed broke the invariant the test stated |
| [`X_JOB_SIM_NONDETERMINISTIC`](/errors/X_JOB_SIM_NONDETERMINISTIC) | one simulateJobs seed produced two different traces |
| [`X_DRILL_FAILED`](/errors/X_DRILL_FAILED) | a fault drill property did not hold |
| [`X_DRILL_SERVICE_MISSING`](/errors/X_DRILL_SERVICE_MISSING) | a fault drill needs a service that is not there |
| [`X_SUBJECT_ERASE_INCOMPLETE`](/errors/X_SUBJECT_ERASE_INCOMPLETE) | a value of the subject survived subjectErase |
| [`X_QUERY_UNINDEXED`](/errors/X_QUERY_UNINDEXED) | a statement no index can serve: the planner can only scan the table |
| [`X_QUERY_SORT_UNSERVED`](/errors/X_QUERY_SORT_UNSERVED) | a limited read sorts its rows: no index serves the order |
| [`X_QUERY_SCALES_WITH_ROWS`](/errors/X_QUERY_SCALES_WITH_ROWS) | a statement shape runs once per row: its count grows with the rows seeded |
| [`X_QUERY_PLAN_UNAVAILABLE`](/errors/X_QUERY_PLAN_UNAVAILABLE) | the database could not answer a generic plan, so no statement was judged |
| [`X_CASSETTE_MISSING`](/errors/X_CASSETTE_MISSING) | a cassette replayed with no recording on disk |
| [`X_CASSETTE_UNUSED`](/errors/X_CASSETTE_UNUSED) | a cassette entry was never replayed |
| [`X_CASSETTE_SECRET`](/errors/X_CASSETTE_SECRET) | a cassette about to be written holds a secret value |
| [`X_CASSETTE_RECORD_REFUSED`](/errors/X_CASSETTE_RECORD_REFUSED) | a cassette recording was refused |
| [`X_TEST_MODULE_MOCK_UNRESTORABLE`](/errors/X_TEST_MODULE_MOCK_UNRESTORABLE) | a mocked module could not be put back at the file boundary |
| [`X_EXERCISE_SETUP_UNSEALED`](/errors/X_EXERCISE_SETUP_UNSEALED) | an exercise setup let a host through the seal |
| [`X_JOB_CRASH_UNBOUNDED`](/errors/X_JOB_CRASH_UNBOUNDED) | a crash proof needs more kill points than its bound |
| [`X_EXERCISE_ACTOR_USER_UNSEATED`](/errors/X_EXERCISE_ACTOR_USER_UNSEATED) | the exercise pass could not seat its actor's x_users row |
| [`X_EXERCISE_INPUT_THREW`](/errors/X_EXERCISE_INPUT_THREW) | an exercise entry's input threw |
| [`X_TEST_SCOPE_UNINSTALLED`](/errors/X_TEST_SCOPE_UNINSTALLED) | a test double was made in a process the testing preload did not set up |
| [`X_TEST_STUB_UNANSWERED`](/errors/X_TEST_STUB_UNANSWERED) | a stubbed primitive was called before any answer was scripted |
| [`X_TEST_STUB_TARGET_UNSUPPORTED`](/errors/X_TEST_STUB_TARGET_UNSUPPORTED) | stub() was handed something that is not an action, llm(), query or job |
| [`X_TEST_EXPECTED_INPUT_INVALID`](/errors/X_TEST_EXPECTED_INPUT_INVALID) | an assertion named an input its primitive's schema rejects |
| [`X_TEST_RUN_JOBS_EXPECTED`](/errors/X_TEST_RUN_JOBS_EXPECTED) | toHaveEnqueued was handed something other than the runJobs fixture |
| [`X_TEST_MAIL_EXPECTED`](/errors/X_TEST_MAIL_EXPECTED) | toHaveSentMail was handed something other than the mail fixture |
| [`X_TEST_ADAPTER_PORT_UNSWAPPABLE`](/errors/X_TEST_ADAPTER_PORT_UNSWAPPABLE) | swapAdapter() was named a port it cannot swap for one test |
| [`X_TEST_FACTORY_INVALID`](/errors/X_TEST_FACTORY_INVALID) | a factory builds a row its own entity refuses |

## UI

| Code | Means |
|---|---|
| [`X_TOKEN_UNKNOWN`](/errors/X_TOKEN_UNKNOWN) | design token role does not exist |
| [`X_THEME_INVALID`](/errors/X_THEME_INVALID) | theme is not `light` or `dark` |
| [`X_UI_RUNTIME_MISSING`](/errors/X_UI_RUNTIME_MISSING) | a host capability `@ultimat3/ui` needs is absent |
| [`X_UI_FORM_PATH_INVALID`](/errors/X_UI_FORM_PATH_INVALID) | a form control name is not a usable field path |
| [`X_UI_CONTRAST_INSUFFICIENT`](/errors/X_UI_CONTRAST_INSUFFICIENT) | a brand palette pairing does not meet WCAG 2.2 AA |
| [`X_UI_QR_CAPACITY`](/errors/X_UI_QR_CAPACITY) | text is too long for a QR code this component can draw |
| [`X_UI_INVALID_VALUE`](/errors/X_UI_INVALID_VALUE) | `@ultimat3/ui` received a value it cannot use |

## CLI and verify

| Code | Means |
|---|---|
| [`X_SOURCE_HEADER_MISSING`](/errors/X_SOURCE_HEADER_MISSING) | a shipped source file opens with no header comment |
| [`X_SOURCE_HEADER_OUT_OF_CONTRACT`](/errors/X_SOURCE_HEADER_OUT_OF_CONTRACT) | a shipped source file's leading header is outside the 1–4 line responsibility contract |
| [`X_SOURCE_HEADER_PIN_STALE`](/errors/X_SOURCE_HEADER_PIN_STALE) | a source-header pin is above the number of violations the tree now holds |
| [`X_SOURCE_HEADER_UNSCANNED`](/errors/X_SOURCE_HEADER_UNSCANNED) | the source-header guard read no shipped source file |
| [`X_DEPENDENCY_NOT_ALLOWLISTED`](/errors/X_DEPENDENCY_NOT_ALLOWLISTED) | a workspace manifest declares an external dependency with no allowlist row |
| [`X_DEPENDENCY_ALLOWLIST_STALE`](/errors/X_DEPENDENCY_ALLOWLIST_STALE) | an allowlist row names a dependency no manifest declares |
| [`X_DEPENDENCY_UNSCANNED`](/errors/X_DEPENDENCY_UNSCANNED) | the dependency guard read no workspace manifest, or no manifest declared a dependency |
| [`X_DEPENDENCY_RANGE_CONFLICT`](/errors/X_DEPENDENCY_RANGE_CONFLICT) | a root and workspace dependency pair has no shared version, or a range cannot be parsed |
| [`X_CLI_UNKNOWN_COMMAND`](/errors/X_CLI_UNKNOWN_COMMAND) | not a command |
| [`X_CLI_BAD_FLAG`](/errors/X_CLI_BAD_FLAG) | flag or positional rejected |
| [`X_CLI_UNEXPECTED`](/errors/X_CLI_UNEXPECTED) | the CLI itself failed |
| [`X_FRAMEWORK_SCHEMA_FAILED`](/errors/X_FRAMEWORK_SCHEMA_FAILED) | a framework table could not be created at boot |
| [`X_VERIFY_FAILED`](/errors/X_VERIFY_FAILED) | one or more verify steps failed |
| [`X_TYPECHECK_FAILED`](/errors/X_TYPECHECK_FAILED) | `tsc` failed |
| [`X_LINT_FAILED`](/errors/X_LINT_FAILED) | Biome failed |
| [`X_TEST_FAILED`](/errors/X_TEST_FAILED) | a test type failed |
| [`X_TEST_NO_FILES`](/errors/X_TEST_NO_FILES) | the test selection matched no files |
| [`X_TEST_SHARD_FAILED`](/errors/X_TEST_SHARD_FAILED) | a test shard exited non-zero |
| [`X_PACKAGE_UNREFERENCED`](/errors/X_PACKAGE_UNREFERENCED) | a published workspace is not in the root tsconfig build graph |
| [`X_VERIFY_SUITE_VANISHED`](/errors/X_VERIFY_SUITE_VANISHED) | a step the committed floor requires had nothing left to check |
| [`X_FILE_TOO_LONG`](/errors/X_FILE_TOO_LONG) | a source file is over 500 lines |
| [`X_GUARD_INVALID`](/errors/X_GUARD_INVALID) | a file in `guards/` exports no usable guard |
| [`X_GUARD_FAILED`](/errors/X_GUARD_FAILED) | an app guard threw instead of returning findings |
| [`X_GUARD_FINDING_INVALID`](/errors/X_GUARD_FINDING_INVALID) | an app guard's finding breaks the error contract |
| [`X_PACKAGE_SHAPE`](/errors/X_PACKAGE_SHAPE) | a workspace package is missing a contract file |
| [`X_ERROR_FIX_INVALID`](/errors/X_ERROR_FIX_INVALID) | an error's fix line is not a runnable instruction |
| [`X_ERROR_FIX_PATH_MISSING`](/errors/X_ERROR_FIX_PATH_MISSING) | an error's fix line cites a file this repository does not have |
| [`X_ERROR_CODE_UNDOCUMENTED`](/errors/X_ERROR_CODE_UNDOCUMENTED) | a shipped error code has no row in the error reference |
| [`X_ERROR_CODE_UNREGISTERED`](/errors/X_ERROR_CODE_UNREGISTERED) | the error reference documents a code no package registers |
| [`X_ERROR_CODE_UNTHROWN`](/errors/X_ERROR_CODE_UNTHROWN) | a registered error code is constructed by nothing and UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts does not list it |
| [`X_ERROR_CODE_UNRESOLVED`](/errors/X_ERROR_CODE_UNRESOLVED) | an error code is written as a name this repository cannot resolve |
| [`X_ERROR_RENDER_UNSAFE`](/errors/X_ERROR_RENDER_UNSAFE) | an error factory builds its `cause:` or `fix:` from an `unknown` in a way that can throw |
| [`X_ERROR_STATUS_MISSING`](/errors/X_ERROR_STATUS_MISSING) | a framework code has no row in `@ultimat3/http`'s closed status table |
| [`X_ERROR_STATUS_BACKLOG_STALE`](/errors/X_ERROR_STATUS_BACKLOG_STALE) | a pin in the status-table ratchet has been resolved and left behind |
| [`X_ERROR_STATUS_UNKNOWN_CODE`](/errors/X_ERROR_STATUS_UNKNOWN_CODE) | the status table maps a code no package declares |
| [`X_CATALOG_KEY_UNREACHABLE`](/errors/X_CATALOG_KEY_UNREACHABLE) | the framework catalog defines a key no framework source can reach |
| [`X_CATALOG_CARRIER_UNSCANNED`](/errors/X_CATALOG_CARRIER_UNSCANNED) | the carried-key rule found no key the framework hands to `t()` through a constant or a property |
| [`X_CLI_FLAG_UNREAD`](/errors/X_CLI_FLAG_UNREAD) | a command declares a flag no code reads |
| [`X_PUBLISH_LIST_INCOMPLETE`](/errors/X_PUBLISH_LIST_INCOMPLETE) | `.github/workflows/release.yml` does not publish every publishable workspace — or contains no `npm publish` command at all |
| [`X_PUBLISH_LIST_UNKNOWN`](/errors/X_PUBLISH_LIST_UNKNOWN) | a publish step names a workspace this tree cannot publish — no such package, or a private one |
| [`X_BENCH_CLAIM_STALE`](/errors/X_BENCH_CLAIM_STALE) | a realtime capacity figure in `CLAUDE.md` is not the figure `scripts/bench/results/*.json` carries |
| [`X_BENCH_URL_REQUIRED`](/errors/X_BENCH_URL_REQUIRED) | the restart benchmark's client shard was started without `--url` |
| [`X_BENCH_STREAM_CLOSED`](/errors/X_BENCH_STREAM_CLOSED) | the restart benchmark's stdout closed before the line it was waiting for |
| [`X_BENCH_RUN_TOO_SHORT`](/errors/X_BENCH_RUN_TOO_SHORT) | `http-hello` was asked for a run under 10 seconds |
| [`X_BENCH_RUN_FAILED`](/errors/X_BENCH_RUN_FAILED) | a bench run produced no publishable figure |
| [`X_WIKI_TABLE_MALFORMED`](/errors/X_WIKI_TABLE_MALFORMED) | a markdown table in `wiki/` does not render as a table |
| [`X_FRAME_DOCS_STALE`](/errors/X_FRAME_DOCS_STALE) | `wiki/Realtime.md` and `FRAME_KINDS` disagree |
| [`X_CHART_VERSION_STALE`](/errors/X_CHART_VERSION_STALE) | `docker/helm/Chart.yaml`'s `version` or `appVersion` is not the version every publishable workspace is stamped at |
| [`X_IMAGE_LIBC_MISMATCH`](/errors/X_IMAGE_LIBC_MISMATCH) | the stage, stage index or external image any Dockerfile in the tree copies its runtime artifact from links a different C library than the runtime provides |
| [`X_IMAGE_GUARD_MISSING`](/errors/X_IMAGE_GUARD_MISSING) | the final stage of any Dockerfile in the tree declares an `ENTRYPOINT` that no `RUN` in that same stage executes |
| [`X_IMAGE_SECRET_UNIGNORED`](/errors/X_IMAGE_SECRET_UNIGNORED) | a `*.dockerignore` in this tree excludes `.env` and `.npmrc` but not `.secrets.key`, or a Dockerfile has no ignore file at all — no `<Dockerfile>.dockerignore`, no `.dockerignore` at or above it |
| [`X_IMAGE_CONTENT_UNIGNORED`](/errors/X_IMAGE_CONTENT_UNIGNORED) | a `*.dockerignore` in this tree does not exclude `**/*.test.ts`, `**/*.test.tsx` or the anchored `docs`, or a later `!` line undoes one |
| [`X_APP_PACKAGE_INVALID`](/errors/X_APP_PACKAGE_INVALID) | the app's `package.json` has no usable `name`/`version` — the manifest never fabricates `app@0.0.0`, because its version is the compatibility gate |
| [`X_BUILD_FAILED`](/errors/X_BUILD_FAILED) | `x build` failed |
| [`X_BUILD_ENTRY_MISSING`](/errors/X_BUILD_ENTRY_MISSING) | the build target's entry file is not in the app |
| [`X_DEPLOY_FAILED`](/errors/X_DEPLOY_FAILED) | a deploy step failed |
| [`X_RUNTIME_DRIVER_SPLIT`](/errors/X_RUNTIME_DRIVER_SPLIT) | the ambient driver is not the one this process serves |
| [`X_SETUP_INSTALL_FAILED`](/errors/X_SETUP_INSTALL_FAILED) | `bun install` failed during `bun run setup` |
| [`X_RELEASE_VERSION_SKEW`](/errors/X_RELEASE_VERSION_SKEW) | a workspace is not at the lockstep version |
| [`X_TRUST_PUBLISHER_MISSING`](/errors/X_TRUST_PUBLISHER_MISSING) | a published package has no OIDC trusted publisher |
| [`X_REGISTRY_BOOTSTRAP_OWED`](/errors/X_REGISTRY_BOOTSTRAP_OWED) | a publishable workspace is absent from the registry — its packument answers 404 |
| [`X_REGISTRY_VERSION_BEHIND`](/errors/X_REGISTRY_VERSION_BEHIND) | the registry holds the package but not the version this tree stamps |
| [`X_REGISTRY_UNATTESTED`](/errors/X_REGISTRY_UNATTESTED) | the stamped version is on the registry with no `dist.attestations`, published by a person |
| [`X_REGISTRY_LATEST_DRIFT`](/errors/X_REGISTRY_LATEST_DRIFT) | the stamped version is on the registry and attested, but npm's default `latest` is not it |
| [`X_REGISTRY_UNREACHABLE`](/errors/X_REGISTRY_UNREACHABLE) | the registry did not answer — timeout, non-2xx, or a 200 that is not a packument |
| [`X_TRUST_PUBLISHER_FAILED`](/errors/X_TRUST_PUBLISHER_FAILED) | attaching a trusted publisher failed |
| [`X_TRUST_2FA_REQUIRED`](/errors/X_TRUST_2FA_REQUIRED) | npm refused the trust change on the credential's class |
| [`X_TRUST_ENVIRONMENT_EMPTY`](/errors/X_TRUST_ENVIRONMENT_EMPTY) | `--environment` was given as an empty string |
| [`X_TRUST_NPM_TOO_OLD`](/errors/X_TRUST_NPM_TOO_OLD) | the npm on `PATH` has no `trust` subcommand |
| [`X_GENERATE_CONFLICT`](/errors/X_GENERATE_CONFLICT) | a generator would overwrite a file |
| [`X_GENERATE_JSON_INVALID`](/errors/X_GENERATE_JSON_INVALID) | a generator's own `merge: 'json'` output does not parse as a JSON object |
| [`X_SCAFFOLD_PATH_ESCAPE`](/errors/X_SCAFFOLD_PATH_ESCAPE) | a generated path resolves outside the scaffold sandbox |
| [`X_NOT_IMPLEMENTED`](/errors/X_NOT_IMPLEMENTED) | a planned command, or a driver whose remote half is unwritten |
| [`X_ERROR_CODE_UNKNOWN`](/errors/X_ERROR_CODE_UNKNOWN) | no package registered this error code |
| [`X_DECLARATION_UNKNOWN`](/errors/X_DECLARATION_UNKNOWN) | no declaration with this name is registered |
| [`X_SEED_ENVIRONMENT`](/errors/X_SEED_ENVIRONMENT) | the seed's tier is not one this environment runs |
| [`X_JOB_UNKNOWN`](/errors/X_JOB_UNKNOWN) | the queue holds no job with this id |
| [`X_FIX_TARGET_UNKNOWN`](/errors/X_FIX_TARGET_UNKNOWN) | the named file is not one of the app's source files |
| [`X_ROADMAP_FILE_MISSING`](/errors/X_ROADMAP_FILE_MISSING) | `docs/idea/14-roadmap.md` does not exist, so no status or artifact can be checked |
| [`X_ROADMAP_STATUS_MISSING`](/errors/X_ROADMAP_STATUS_MISSING) | a milestone has no row, or its row's status cell holds neither ✅ nor 🚧 |
| [`X_ROADMAP_MILESTONE_UNVERIFIED`](/errors/X_ROADMAP_MILESTONE_UNVERIFIED) | a milestone the table marks ✅ is missing a package or file its own **Ships** column names |
| [`X_ROADMAP_MILESTONE_UNTRACKED`](/errors/X_ROADMAP_MILESTONE_UNTRACKED) | a milestone row exists that `REQUIRED_ARTIFACTS` has no entry for, so its status marker verifies nothing |
| [`X_SCAFFOLD_OVERRIDES_EMPTY`](/errors/X_SCAFFOLD_OVERRIDES_EMPTY) | no `@ultimat3/*` workspace manifests were found, so the smoke app would install from the npm registry |
| [`X_REFERENCE_APP_REGRESSED`](/errors/X_REFERENCE_APP_REGRESSED) | a step of a tracked app's own gate that was passing now fails — or the gate produced no step table at all |
| [`X_REFERENCE_APP_PIN_STALE`](/errors/X_REFERENCE_APP_PIN_STALE) | a step pinned as failing in the app's `expectedRed` now passes |
| [`X_REFERENCE_APP_UNREFERENCED`](/errors/X_REFERENCE_APP_UNREFERENCED) | a tracked app typechecks but the root `tsconfig.json` does not reference it |
| [`X_REFERENCE_APP_NO_FLOOR`](/errors/X_REFERENCE_APP_NO_FLOOR) | a tracked app's `x.verify.json` does not cover the steps its own gate ran — the file is missing, empty, or behind |
| [`X_SCAFFOLD_GATE_RED`](/errors/X_SCAFFOLD_GATE_RED) | the freshly scaffolded app's own `bun run verify` went red — or printed a step table this gate cannot match against the declared steps, or reported `budgets` as `skipped` rather than green |
| [`X_SCAFFOLD_FIRST_RUN_FAILED`](/errors/X_SCAFFOLD_FIRST_RUN_FAILED) | a first-run command failed inside a freshly scaffolded app |
| [`X_DOC_FIX_UNRUNNABLE`](/errors/X_DOC_FIX_UNRUNNABLE) | a `Fix` cell of this page cannot be run as written |
| [`X_DOC_FIX_UNSCANNED`](/errors/X_DOC_FIX_UNSCANNED) | `wiki/Error-Codes.md` could not be read, or holds no `Fix` column |
| [`X_DOC_FIX_DISAGREES`](/errors/X_DOC_FIX_DISAGREES) | a Fix cell on this page names no remedy its code's throw sites register |
| [`X_DOC_FIX_DISAGREES_PIN_STALE`](/errors/X_DOC_FIX_DISAGREES_PIN_STALE) | fewer Fix cells disagree with their registered fix than the ratchet allows |
| [`X_DOC_CAUSE_ECHOES_TITLE`](/errors/X_DOC_CAUSE_ECHOES_TITLE) | a row of this page states its title again as its typical cause |
| [`X_DOC_COMMAND_UNKNOWN`](/errors/X_DOC_COMMAND_UNKNOWN) | a page in `wiki/` or `docs/` hands the reader an `x` invocation this build cannot run |
| [`X_DOC_COMMAND_ALLOWANCE_STALE`](/errors/X_DOC_COMMAND_ALLOWANCE_STALE) | an entry in `DOC_COMMAND_ALLOWANCES` matches nothing in the tree |
| [`X_DOC_COMMAND_UNSCANNED`](/errors/X_DOC_COMMAND_UNSCANNED) | no page was read, so nothing was checked |
| [`X_DOC_COMMAND_PIN_STALE`](/errors/X_DOC_COMMAND_PIN_STALE) | a pinned unresolved `x` citation (a page + invocation site in `DOC_COMMAND_PINS`) is no longer there, or a page holds one its pins do not name |
| [`X_DOC_TEST_PATH_BARE`](/errors/X_DOC_TEST_PATH_BARE) | a page hands the reader `bun test <path>` with no leading `./` |
| [`X_DOC_TEST_PATH_UNSCANNED`](/errors/X_DOC_TEST_PATH_UNSCANNED) | no page was read, so no `bun test` path was checked |
| [`X_TSCONFIG_PATH_MISSING`](/errors/X_TSCONFIG_PATH_MISSING) | a package exports a TypeScript subpath with no row in `tsconfig.base.json` `paths` |
| [`X_TSCONFIG_PATH_STALE`](/errors/X_TSCONFIG_PATH_STALE) | a `tsconfig.base.json` `paths` row names a subpath no package exports, or a file other than the one it exports |
| [`X_TSCONFIG_PATHS_UNSCANNED`](/errors/X_TSCONFIG_PATHS_UNSCANNED) | no package subpath export was read, so the `paths` rows were checked against nothing |
| [`X_DOC_GATE_STEPS_STALE`](/errors/X_DOC_GATE_STEPS_STALE) | a page states how many steps `x verify` runs, or enumerates them, and describes a gate this build does not run |
| [`X_DOC_SETUP_COMMAND_STALE`](/errors/X_DOC_SETUP_COMMAND_STALE) | a page describes a `bun run setup` the scaffold does not write — a step list missing one of its steps, or a step count that is not the script's |
| [`X_DOC_SETUP_COMMANDS_UNSCANNED`](/errors/X_DOC_SETUP_COMMANDS_UNSCANNED) | the rule read no list, or no count, or could not read `binSetup()` at all |
| [`X_DOC_GATE_STEPS_UNSCANNED`](/errors/X_DOC_GATE_STEPS_UNSCANNED) | no page states a step count or enumerates the gate, so the rule read nothing |
| [`X_DOC_SETUP_COMMAND_STALE`](/errors/X_DOC_SETUP_COMMAND_STALE) | a page enumerating what a scaffolded app's `bun run setup` runs describes a script `x new` does not write |
| [`X_DOC_SETUP_COMMANDS_UNSCANNED`](/errors/X_DOC_SETUP_COMMANDS_UNSCANNED) | no page enumerates `bun run setup`'s sequence, so the rule read nothing |
| [`X_DOC_CHANGELOG_SECTION_INVALID`](/errors/X_DOC_CHANGELOG_SECTION_INVALID) | a `CHANGELOG.md` section is not one section |
| [`X_DOC_CHANGELOG_UNRELEASED_BREAKING`](/errors/X_DOC_CHANGELOG_UNRELEASED_BREAKING) | `BREAKING —` entries sit under `## [Unreleased]` on a tagged commit |
| [`X_DOC_MIGRATION_COUNT_STALE`](/errors/X_DOC_MIGRATION_COUNT_STALE) | a `wiki/Upgrading.md` count is not the count of the section it names |
| [`X_DOC_MIGRATION_UNSCANNED`](/errors/X_DOC_MIGRATION_UNSCANNED) | no row in `wiki/Upgrading.md` sends the reader to a single version section, so the rule read nothing |
| [`X_DOC_MIGRATION_UNPAIRED`](/errors/X_DOC_MIGRATION_UNPAIRED) | a `BREAKING —` line and the Upgrading entry that migrates it do not pair one-to-one |
| [`X_DOC_MIGRATION_RANGE_STALE`](/errors/X_DOC_MIGRATION_RANGE_STALE) | a walkthrough cites an entry or upgrade step it has no row for |
| [`X_RELEASE_UNRELEASED_MISSING`](/errors/X_RELEASE_UNRELEASED_MISSING) | `CHANGELOG.md` has no `## [Unreleased]` heading, so a release has nothing to promote |
| [`X_README_EXAMPLE_UNCOMPILED`](/errors/X_README_EXAMPLE_UNCOMPILED) | a package `README.md` gained a `ts`/`tsx` fence that does not compile |
| [`X_README_EXAMPLE_PIN_STALE`](/errors/X_README_EXAMPLE_PIN_STALE) | a package's pinned failing-fence count is higher than the number that actually fail |
| [`X_README_EXAMPLE_UNSCANNED`](/errors/X_README_EXAMPLE_UNSCANNED) | `tsc` did not run over the extracted fences |
| [`X_README_SAMPLE_DRIFT`](/errors/X_README_SAMPLE_DRIFT) | the root `README.md`'s code sample is not the file its `readme-sample` marker names |
| [`X_README_FACTS_DRIFT`](/errors/X_README_FACTS_DRIFT) | the root `README.md`'s generated facts table is not what the tree says |
| [`X_PRODUCTION_APPS_DRIFT`](/errors/X_PRODUCTION_APPS_DRIFT) | a page answering who uses Ultimate does not carry what `PRODUCTION_APPS` renders |
| [`X_ADOPTION_CLAIM_UNGENERATED`](/errors/X_ADOPTION_CLAIM_UNGENERATED) | a published page says who uses Ultimate outside the generated production-apps block |
| [`X_PACKAGE_README_SHAPE`](/errors/X_PACKAGE_README_SHAPE) | a publishable package's README lacks, in its first 30 lines, the heading, one sentence, an install line, an example or a link to its `homepage` wiki page — or a `README_SHAPE_PINS` row exempts nothing |
| [`X_PACKAGE_KEYWORDS_MISSING`](/errors/X_PACKAGE_KEYWORDS_MISSING) | a publishable package's `package.json` has no non-empty `keywords` array |
| [`X_VERSION_STAMP_STALE`](/errors/X_VERSION_STAMP_STALE) | a page stamps a version that is not the version this tree carries |
| [`X_VERSION_STAMP_DUPLICATE`](/errors/X_VERSION_STAMP_DUPLICATE) | more than one page carries a version stamp |
| [`X_VERSION_LOCKSTEP_BROKEN`](/errors/X_VERSION_LOCKSTEP_BROKEN) | the publishable workspaces do not all carry one version |
| [`X_VERSION_STAMP_UNSCANNED`](/errors/X_VERSION_STAMP_UNSCANNED) | no workspace manifest carried a version, so there was nothing to compare against |
| [`X_COVERAGE_BELOW`](/errors/X_COVERAGE_BELOW) | a package's own `src/` is under the coverage floor |
| [`X_COVERAGE_PIN_STALE`](/errors/X_COVERAGE_PIN_STALE) | a package now clears its coverage pin and the pin is still there |
| [`X_COVERAGE_UNMEASURED`](/errors/X_COVERAGE_UNMEASURED) | coverage was read from a suite that did not measure it |
| [`X_DOC_FILE_COUNT_STALE`](/errors/X_DOC_FILE_COUNT_STALE) | a page states a file count for a generator that the generator no longer emits |
| [`X_DOC_FILE_COUNT_UNSCANNED`](/errors/X_DOC_FILE_COUNT_UNSCANNED) | no page states a generator file count, so the rule read nothing |
| [`X_DOC_RELEASE_FACT_STALE`](/errors/X_DOC_RELEASE_FACT_STALE) | a page states how many packages ship and the tree has a different number |
| [`X_DOC_RELEASE_FACT_UNSCANNED`](/errors/X_DOC_RELEASE_FACT_UNSCANNED) | no page states a package count, so the rule read nothing |
| [`X_DOC_PACKAGE_GRAPH_STALE`](/errors/X_DOC_PACKAGE_GRAPH_STALE) | the dependency graph `docs/architecture/01-package-map.md` draws is not the one the manifests declare |
| [`X_INDEX_ORDER_UNGUARDED`](/errors/X_INDEX_ORDER_UNGUARDED) | an ordering assertion built on `indexOf` with nothing asserting the needle is present |
| [`X_INDEX_ORDER_PIN_STALE`](/errors/X_INDEX_ORDER_PIN_STALE) | a package is pinned above the unguarded assertions it now has |
| [`X_INDEX_ORDER_PIN_UNEXPLAINED`](/errors/X_INDEX_ORDER_PIN_UNEXPLAINED) | a package is pinned with a blank reason |
| [`X_INDEX_ORDER_UNSCANNED`](/errors/X_INDEX_ORDER_UNSCANNED) | the rule read nothing, so no ordering assertion was checked |
| [`X_SKIP_CLEANUP_UNREACHED`](/errors/X_SKIP_CLEANUP_UNREACHED) | a test file resets a process-global registry from inside a `.skipIf(` block, where it never runs |
| [`X_SKIP_CLEANUP_UNSCANNED`](/errors/X_SKIP_CLEANUP_UNSCANNED) | the rule read nothing, so no skipped suite was checked |
| [`X_TEST_DISCOVERY_UNSEEN`](/errors/X_TEST_DISCOVERY_UNSEEN) | the tree holds a test file the gate's test discovery cannot yield, or one outside the one convention |
| [`X_TEST_DISCOVERY_UNSCANNED`](/errors/X_TEST_DISCOVERY_UNSCANNED) | the discovery walk read zero files, so no test-shaped file was checked |
| [`X_PROBE_DATABASE_FIXED`](/errors/X_PROBE_DATABASE_FIXED) | a test creates a database under a name that is the same on every run |
| [`X_SQL_LITERAL_COPY`](/errors/X_SQL_LITERAL_COPY) | a module other than `packages/db/src/sql.ts` turns `'` into `''` itself |
| [`X_SQL_LITERAL_UNSCANNED`](/errors/X_SQL_LITERAL_UNSCANNED) | the rule read nothing, so no copy of the escape was checked |
| [`X_BROWSER_TRANSPORT_BYPASS`](/errors/X_BROWSER_TRANSPORT_BYPASS) | browser-reachable code opens its own connection instead of using the one seam |
| [`X_BROWSER_TRANSPORT_UNSCANNED`](/errors/X_BROWSER_TRANSPORT_UNSCANNED) | the rule's `fetch` seam no longer calls `fetch`, so every bypass check is vacuous |
| [`X_BROWSER_SERVER_BARREL`](/errors/X_BROWSER_SERVER_BARREL) | browser-reachable code imports a package's server barrel where the package publishes a browser entry |
| [`X_CHANNEL_LITERAL`](/errors/X_CHANNEL_LITERAL) | a channel topic is spelled outside its `channel()` declaration |
| [`X_CHANNEL_LITERAL_UNSCANNED`](/errors/X_CHANNEL_LITERAL_UNSCANNED) | the rule's seam was not among the files scanned |
| [`X_SEAL_CALL_OUTSIDE_CORE`](/errors/X_SEAL_CALL_OUTSIDE_CORE) | a package writes its own AES call instead of calling `seal()` / `open()` |
| [`X_SEAL_CALL_UNSCANNED`](/errors/X_SEAL_CALL_UNSCANNED) | the rule's seam was not among the files scanned |
| [`X_KEYED_HASHER`](/errors/X_KEYED_HASHER) | an HMAC is taken with a keyed `new Bun.CryptoHasher(alg, key)` instead of `hmac()` |
| [`X_KEYED_HASHER_EXEMPT_STALE`](/errors/X_KEYED_HASHER_EXEMPT_STALE) | a `KEYED_HASHER_EXEMPT` row excuses nothing |
| [`X_INSTRUMENT_SLOT_FORBIDDEN`](/errors/X_INSTRUMENT_SLOT_FORBIDDEN) | a package exports a single observer slot instead of emitting on the instrumentation bus |
| [`X_INSTRUMENT_SLOT_ALLOWANCE_STALE`](/errors/X_INSTRUMENT_SLOT_ALLOWANCE_STALE) | an `INSTRUMENT_SLOT_ALLOWED` row excuses nothing |
| [`X_ADAPTER_PORT_INCOMPLETE`](/errors/X_ADAPTER_PORT_INCOMPLETE) | an adapter port is missing part of its contract, or a backend is swapped outside one |
| [`X_CLI_OUTBOUND_UNDECLARED`](/errors/X_CLI_OUTBOUND_UNDECLARED) | a non-test `packages/cli/src` file spells a host not on the allowlist |
| [`X_CLI_OUTBOUND_ALLOWANCE_STALE`](/errors/X_CLI_OUTBOUND_ALLOWANCE_STALE) | an allowlist row names a host the CLI no longer spells |
| [`X_PRIVATE_NAME`](/errors/X_PRIVATE_NAME) | a private name is in a tracked file |
| [`X_PRIVATE_NAMES_UNSET`](/errors/X_PRIVATE_NAMES_UNSET) | the private-name secret is missing where the names are required |
| [`X_GUARD_LOAD_FAILED`](/errors/X_GUARD_LOAD_FAILED) | a repository guard could not load its own imports, so it checked nothing |
| [`X_BUDGET_RAISE_UNSTATED`](/errors/X_BUDGET_RAISE_UNSTATED) | a route's budget went up with no measured number and no reason beside it |
| [`X_BUDGET_BASE_MISSING`](/errors/X_BUDGET_BASE_MISSING) | `budget-raises` had no `origin/main` to compare against, and fetching it failed |
| [`X_PIN_RAISE_UNSTATED`](/errors/X_PIN_RAISE_UNSTATED) | a ratchet pin in `scripts/lib/*-pins.ts` is higher than at `origin/main`'s tip with no `why:` on the row |
| [`X_PIN_BASE_MISSING`](/errors/X_PIN_BASE_MISSING) | `pin-raises` had no `origin/main` to compare against, and fetching it failed |
| [`X_CORPUS_UNSCANNED`](/errors/X_CORPUS_UNSCANNED) | a whole-tree guard read fewer files than its scope's floor, or could not read part of it, or `scripts/lib/workspaces.ts` enumerated no publishable workspace (`registry-audit`, `release`, `list-workspaces`) |
| [`X_DOC_UNRELEASED_STALE`](/errors/X_DOC_UNRELEASED_STALE) | a current page calls a version "unreleased" that `CHANGELOG.md` has dated — or, at a release commit or with `[Unreleased]` empty, says `As of Unreleased`, "not yet tagged", what the next major does, or carries a Known-Gaps `` `main` `` cell (`scripts/doc-unreleased.ts`) |
| [`X_DOC_UNRELEASED_PIN_STALE`](/errors/X_DOC_UNRELEASED_PIN_STALE) | a page is pinned above its stale "unreleased" lines |
| [`X_LLMS_TXT_DRIFT`](/errors/X_LLMS_TXT_DRIFT) | `llms.txt`'s generated package or wiki list differs from what it is generated from |
| [`X_GUARDS_DOC_DRIFT`](/errors/X_GUARDS_DOC_DRIFT) | `docs/architecture/guards.md` differs from the guard headers it is generated from |
| [`X_BOUNDARY_VIOLATION`](/errors/X_BOUNDARY_VIOLATION) | a framework package imports one it may not under `scripts/lib/tiers.ts` — this repository's own tier rule, distinct from an app's `X_BOUNDARY_*` codes |
| [`X_DOC_PATH_DEAD`](/errors/X_DOC_PATH_DEAD) | a published page names, in backticks, a `packages/…`, `scripts/…` or `docs/…` path that exists neither in this repository nor in a tracked app |
| [`X_ROOT_BIN_REINTRODUCED`](/errors/X_ROOT_BIN_REINTRODUCED) | the repository root has a `bin/` again (file, directory, or empty directory) |
| [`X_VERIFY_PART_UNNAMED`](/errors/X_VERIFY_PART_UNNAMED) | `bun run scripts/verify-parts.ts` found a gate-part document that names no run attempt, or none at all, in the `verify` job's download |
| [`X_URL_PATHNAME_AS_PATH`](/errors/X_URL_PATHNAME_AS_PATH) | a source reads `.pathname` off a URL built from `import.meta.url` (or destructures it, or builds a `file://` URL from a string) and uses it as a filesystem path |
| [`X_RELATIVE_PATH_NOT_POSIX`](/errors/X_RELATIVE_PATH_NOT_POSIX) | a host `relative()` answer is used without `toPosix` |
| [`X_SET_COOKIE_HAND_BUILT`](/errors/X_SET_COOKIE_HAND_BUILT) | a `Set-Cookie` attribute is spelled in a literal, or a `Set-Cookie` header is written by name, outside `packages/core/src/cookie.ts` and `packages/http/src/set-cookie.ts` |
| [`X_SET_COOKIE_PIN_STALE`](/errors/X_SET_COOKIE_PIN_STALE) | a pin in `SET_COOKIE_PINS` is above what its file holds |
| [`X_SET_COOKIE_UNSCANNED`](/errors/X_SET_COOKIE_UNSCANNED) | the serializer's own module was not among the files scanned, so no verdict was reached |
| [`X_FACTORY_NAME_SPELLING`](/errors/X_FACTORY_NAME_SPELLING) | a public package entry exports a retired factory spelling |
| [`X_CORE_THROWER_UNCALLED`](/errors/X_CORE_THROWER_UNCALLED) | a `@ultimat3/core` export that throws a coded error has no non-test caller |
| [`X_CORE_THROWER_PIN_STALE`](/errors/X_CORE_THROWER_PIN_STALE) | a pinned uncalled core thrower now has a caller or no longer exists |
| [`X_CORE_THROWERS_UNSCANNED`](/errors/X_CORE_THROWERS_UNSCANNED) | the core-thrower rule read no file |
| [`X_SQL_EXPORT_UNREAD`](/errors/X_SQL_EXPORT_UNREAD) | a package entry exports a `SQL_*` statement nothing outside the package reads |
| [`X_SQL_EXPORT_UNSCANNED`](/errors/X_SQL_EXPORT_UNSCANNED) | the SQL-export rule read no package entry file |
| [`X_WIKI_EXAMPLE_UNCOMPILED`](/errors/X_WIKI_EXAMPLE_UNCOMPILED) | a fenced `ts`/`tsx` example on a wiki page does not typecheck, beyond its page's pin |
| [`X_WIKI_EXAMPLE_PIN_STALE`](/errors/X_WIKI_EXAMPLE_PIN_STALE) | a page's wiki-fence pin is above what fails on it now |
| [`X_WIKI_EXAMPLE_UNSCANNED`](/errors/X_WIKI_EXAMPLE_UNSCANNED) | no wiki fence was read, or `tsc` refused to run |
| [`X_WIKI_ANCHOR_DEAD`](/errors/X_WIKI_ANCHOR_DEAD) | a `Page#anchor` link lands on no heading, or on a page that does not exist |
| [`X_WIKI_ANCHOR_UNSCANNED`](/errors/X_WIKI_ANCHOR_UNSCANNED) | no wiki anchor link was read |
| [`X_WIKI_TABLE_UNSCANNED`](/errors/X_WIKI_TABLE_UNSCANNED) | no wiki table was read |
| [`X_KNOWN_GAP_LINK_MALFORMED`](/errors/X_KNOWN_GAP_LINK_MALFORMED) | a Known-Gaps `[B<n>]` link does not resolve to its backlog row, or the line names no issue or the wrong one |
| [`X_KNOWN_GAP_UNSCANNED`](/errors/X_KNOWN_GAP_UNSCANNED) | `wiki/Known-Gaps.md` is missing or cites no `[B<n>]` row |
| [`X_KNOWN_GAP_UNPINNED`](/errors/X_KNOWN_GAP_UNPINNED) | an Open row of `wiki/Known-Gaps.md` links no test asserting today's behaviour, or a dead one |
| [`X_KNOWN_GAP_PIN_STALE`](/errors/X_KNOWN_GAP_PIN_STALE) | `scripts/lib/known-gaps-unpinned-pins.ts` lists a row that is pinned now, closed or renamed |
| [`X_DOC_TUTORIAL_DIVERGED`](/errors/X_DOC_TUTORIAL_DIVERGED) | a tutorial's command, run on a scaffold of this checkout, exits otherwise than the page shows or prints no line matching its `✓`/`✗` summary |
| [`X_DOC_UID_STALE`](/errors/X_DOC_UID_STALE) | `docs/ops` states a uid the image it names does not run |
| [`X_DOC_UID_UNSCANNED`](/errors/X_DOC_UID_UNSCANNED) | no chart `runAsUser` was read, or no uid was attributed to one of the two images |
| [`X_DOC_BOUNDARY_RULES_STALE`](/errors/X_DOC_BOUNDARY_RULES_STALE) | `docs/architecture/02-boundaries.md` states a rule count or codes that differ from `BOUNDARY_CODES` |
| [`X_DOC_BOUNDARY_RULES_UNSCANNED`](/errors/X_DOC_BOUNDARY_RULES_UNSCANNED) | the boundary-rules section, its count sentence or its table is missing |
| [`X_PLAN_STATUS_INVALID`](/errors/X_PLAN_STATUS_INVALID) | a `docs/plans/**/status.yml` does not parse, or its `status` or a slice's `status` is not `not_started \| in_progress \| blocked \| complete \| superseded` |
| [`X_PLAN_STATUS_UNSCANNED`](/errors/X_PLAN_STATUS_UNSCANNED) | no `docs/plans/**/status.yml` was found, so no tracker was checked |
| [`X_GUARDS_DOC_UNSCANNED`](/errors/X_GUARDS_DOC_UNSCANNED) | the generator found no runnable `scripts/*.ts` that emits a code |
| [`X_CLAUDE_MD_OVERSIZE`](/errors/X_CLAUDE_MD_OVERSIZE) | a `CLAUDE.md` is over its byte ceiling: 16 KB for the root, 24 KB for a package, or a package file's pin in `scripts/lib/claude-md-size-pins.ts` |
| [`X_CLAUDE_MD_UNSCANNED`](/errors/X_CLAUDE_MD_UNSCANNED) | there is no root `CLAUDE.md`, or no `packages/*/CLAUDE.md` was found |
| [`X_NEW_ERROR_CODE_INVALID`](/errors/X_NEW_ERROR_CODE_INVALID) | `bun run new-error-code` was called without what it needs, or for a package with no `errors.ts` |
| [`X_NEW_ERROR_CODE_EXISTS`](/errors/X_NEW_ERROR_CODE_EXISTS) | the code is already registered or already documented |
| [`X_NEW_ERROR_CODE_PATTERN_UNKNOWN`](/errors/X_NEW_ERROR_CODE_PATTERN_UNKNOWN) | the package's `errors.ts` has no shape `new-error-code` can add to |
| [`X_FRAMEWORK_TABLE_UNAPPLIED`](/errors/X_FRAMEWORK_TABLE_UNAPPLIED) | a package declares a framework table in a `create table` and no boot path creates it |
| [`X_FIX_SHELL_ARG_UNSCREENED`](/errors/X_FIX_SHELL_ARG_UNSCREENED) | a value is spliced into the SHELL COMMAND POSITION of a `fix:` line without being screened |
| [`X_FIX_SHELL_ARG_PIN_STALE`](/errors/X_FIX_SHELL_ARG_PIN_STALE) | a package is pinned above the number of unscreened `fix:` substitutions it still has |
| [`X_FIX_SHELL_ARG_PIN_UNEXPLAINED`](/errors/X_FIX_SHELL_ARG_PIN_UNEXPLAINED) | a package is pinned with a blank reason |
| [`X_SPAWN_UNTIMED`](/errors/X_SPAWN_UNTIMED) | a package spawns more child processes with no timeout than it is pinned at |
| [`X_SPAWN_TIMEOUT_PIN_STALE`](/errors/X_SPAWN_TIMEOUT_PIN_STALE) | a package is pinned above the number of untimed spawns it still has |
| [`X_SPAWN_TIMEOUT_PIN_UNEXPLAINED`](/errors/X_SPAWN_TIMEOUT_PIN_UNEXPLAINED) | a package's untimed-spawn pin has a blank reason |
| [`X_SPAWN_TIMED_OUT`](/errors/X_SPAWN_TIMED_OUT) | a command a gate script ran did not finish within its deadline and was killed |
| [`X_FETCH_UNBOUNDED`](/errors/X_FETCH_UNBOUNDED) | a package makes more shipped `fetch(` calls with no signal than it is pinned at |
| [`X_FETCH_DEADLINE_PIN_STALE`](/errors/X_FETCH_DEADLINE_PIN_STALE) | a package's unsignalled-fetch pin is above what the tree holds |
| [`X_FETCH_DEADLINE_PIN_UNEXPLAINED`](/errors/X_FETCH_DEADLINE_PIN_UNEXPLAINED) | a package's unsignalled-fetch pin has a blank reason |
| [`X_FIX_SHELL_ARG_UNSCANNED`](/errors/X_FIX_SHELL_ARG_UNSCANNED) | the rule read no source file |
| [`X_FIX_PROSE`](/errors/X_FIX_PROSE) | a package holds more `fix:` lines that open with prose than its pin allows |
| [`X_FIX_PROSE_PIN_STALE`](/errors/X_FIX_PROSE_PIN_STALE) | a package is pinned above the number of prose `fix:` lines it holds |
| [`X_FIX_PROSE_PIN_UNEXPLAINED`](/errors/X_FIX_PROSE_PIN_UNEXPLAINED) | a `FIX_PROSE_PINS` row carries a blank reason |
| [`X_FIX_PROSE_UNSCANNED`](/errors/X_FIX_PROSE_UNSCANNED) | `fix-prose` read no `fix:` line at all |
| [`X_VOCABULARY_REDECLARED`](/errors/X_VOCABULARY_REDECLARED) | a closed set of string literals is declared a second time |
| [`X_VOCABULARY_UNSCANNED`](/errors/X_VOCABULARY_UNSCANNED) | the vocabulary rule read nothing, or the owning module declares nothing it can read |
| [`X_FROZEN_RECORD_INFERRED`](/errors/X_FROZEN_RECORD_INFERRED) | `const X: Readonly<Record<K, V>> = Object.freeze({…})` lets the type argument be INFERRED |
| [`X_FROZEN_RECORD_UNSCANNED`](/errors/X_FROZEN_RECORD_UNSCANNED) | the freeze rule found no `Object.freeze` at all, or no correct form to recognise |
| [`X_CONFIG_READER_PIN_UNEXPLAINED`](/errors/X_CONFIG_READER_PIN_UNEXPLAINED) | an `AppConfig` leaf key is pinned with a blank reason |
| [`X_CONFIG_READER_APP_UNREAD`](/errors/X_CONFIG_READER_APP_UNREAD) | a `CONFIG_READER_PINS` row says app code reads a key and neither tracked app does |
| [`X_SECRET_COMPARE_PIN_UNEXPLAINED`](/errors/X_SECRET_COMPARE_PIN_UNEXPLAINED) | a comparison site is pinned with a blank reason on the secret-comparison ratchet |
| [`X_PROTO_CHAIN_INDEX_PIN_UNEXPLAINED`](/errors/X_PROTO_CHAIN_INDEX_PIN_UNEXPLAINED) | a package is pinned with a blank reason on the prototype-index ratchet |
| [`X_FRAMEWORK_TABLE_UNSCANNED`](/errors/X_FRAMEWORK_TABLE_UNSCANNED) | the framework-table rule read nothing — no `create table` in `packages/*/src`, or a `FRAMEWORK_SCHEMA` that names no table |
| [`X_DOC_PACKAGE_GRAPH_UNSCANNED`](/errors/X_DOC_PACKAGE_GRAPH_UNSCANNED) | the package map draws no graph this rule can read |
| [`X_LOCKFILE_STALE`](/errors/X_LOCKFILE_STALE) | `bun.lock` records an `@ultimat3/*` range that the `package.json` it was generated from no longer declares |
| [`X_RELEASE_FLAG_UNKNOWN`](/errors/X_RELEASE_FLAG_UNKNOWN) | `scripts/release.ts` was passed a flag it does not declare |
| [`X_RELEASE_VERSION_UNSTATED`](/errors/X_RELEASE_VERSION_UNSTATED) | a release was asked for and neither `--version` nor `--bump` was given |
| [`X_RELEASE_TREE_DIRTY`](/errors/X_RELEASE_TREE_DIRTY) | `scripts/release.ts` was run over a working tree with uncommitted changes |
| [`X_RELEASE_VERSION_INVALID`](/errors/X_RELEASE_VERSION_INVALID) | `scripts/release.ts` was asked for a version that does not move forward, or for two at once |
| [`X_RELEASE_MAJOR_WINDOW`](/errors/X_RELEASE_MAJOR_WINDOW) | `scripts/release.ts` was asked for a major inside the 90-day window, or a released major's section is dated inside it |
| [`X_BREAKING_ON_MAIN`](/errors/X_BREAKING_ON_MAIN) | a change to `main` carries a `BREAKING —` entry under `[Unreleased]` while the major window is closed |
| [`X_RELEASE_UNDEPRECATED_REMOVAL`](/errors/X_RELEASE_UNDEPRECATED_REMOVAL) | a name a package's `src/index.ts` exported at the previous release tag is gone, and that tag never marked it `@deprecated` |
| [`X_CHANGELOG_HIGHLIGHTS_MISSING`](/errors/X_CHANGELOG_HIGHLIGHTS_MISSING) | a release section from 30.0.0 on does not open with `### Highlights` of one to five bullets |
| [`X_RELEASE_TAG_UNREACHABLE`](/errors/X_RELEASE_TAG_UNREACHABLE) | `scripts/release-due.ts` found no `vX.Y.Z` tag reachable from HEAD, or could not read the commits since it |
| [`X_RELEASE_WINDOW_UNREADABLE`](/errors/X_RELEASE_WINDOW_UNREADABLE) | `scripts/release-due.ts` found the last release tag but `git log v<tag>..HEAD` failed |
| [`X_RELEASE_HEAD_NOT_MAIN`](/errors/X_RELEASE_HEAD_NOT_MAIN) | `scripts/release-due.ts` refused to answer because HEAD is not the tip of `origin/main` |
| [`X_HEALTH_ROW_UNREADABLE`](/errors/X_HEALTH_ROW_UNREADABLE) | `scripts/health.ts` could not read a row's command, so no verdict for that row exists |
| [`X_TEST_BARE_ERROR`](/errors/X_TEST_BARE_ERROR) | a test reports its own verdict by throwing a bare `Error` |
| [`X_TEST_BARE_ERROR_PIN_STALE`](/errors/X_TEST_BARE_ERROR_PIN_STALE) | a package is pinned above the number of bare-`Error` throws it actually has |
| [`X_TEST_BARE_ERROR_UNSCANNED`](/errors/X_TEST_BARE_ERROR_UNSCANNED) | no test file was read, so every package reported zero |
| [`X_SOURCE_BARE_ERROR`](/errors/X_SOURCE_BARE_ERROR) | shipped source throws a bare builtin `Error` |
| [`X_SOURCE_BARE_ERROR_EXEMPT_STALE`](/errors/X_SOURCE_BARE_ERROR_EXEMPT_STALE) | an exemption in the bare-`Error` inventory names a site that holds no bare throw |
| [`X_TEST_REAL_SLEEP`](/errors/X_TEST_REAL_SLEEP) | a test waits for the wall clock — `Bun.sleep(n)`, `setTimeout(…, n > 1)`, `setInterval` — with no `// real-clock:` reason |
| [`X_TEST_REAL_SLEEP_PIN_STALE`](/errors/X_TEST_REAL_SLEEP_PIN_STALE) | a package is pinned at more wall-clock test waits than the tree holds |
| [`X_TEST_REAL_SLEEP_UNSCANNED`](/errors/X_TEST_REAL_SLEEP_UNSCANNED) | the real-sleep rule read no test file |
| [`X_NODE_IMPORT_UNEXPLAINED`](/errors/X_NODE_IMPORT_UNEXPLAINED) | a `node:` builtin is imported with no `why:` comment on it or directly above |
| [`X_NODE_IMPORT_PIN_STALE`](/errors/X_NODE_IMPORT_PIN_STALE) | a package is pinned above the number of unexplained `node:` imports it actually has |
| [`X_NODE_IMPORT_UNSCANNED`](/errors/X_NODE_IMPORT_UNSCANNED) | no source file was read, so every package reported zero |
| [`X_TEST_FIX_UNRUNNABLE`](/errors/X_TEST_FIX_UNRUNNABLE) | a `fix:` a test writes or asserts cites a command this build cannot run |
| [`X_TEST_FIX_PIN_STALE`](/errors/X_TEST_FIX_PIN_STALE) | a package is pinned above the number of unrunnable test `fix:` lines it has |
| [`X_TEST_FIX_UNSCANNED`](/errors/X_TEST_FIX_UNSCANNED) | no test file matched, so the rule reported over a file set it never read |
| [`X_TEST_THROW_NOT_THROWN`](/errors/X_TEST_THROW_NOT_THROWN) | `expect(fn).toThrow(…)` is given a callback that **returns** an error instead of throwing one |
| [`X_TEST_TYPECHECK_REGRESSED`](/errors/X_TEST_TYPECHECK_REGRESSED) | a package's own tests carry more `tsc` errors than the ratchet pins |
| [`X_TEST_TYPECHECK_PIN_STALE`](/errors/X_TEST_TYPECHECK_PIN_STALE) | a pin in the test-typecheck ratchet is above what remains, or names a directory that is not a package |
| [`X_TEST_TYPECHECK_UNSCANNED`](/errors/X_TEST_TYPECHECK_UNSCANNED) | the test program did not compile, so the rule reported over tests it never read |
| [`X_CATCH_RENDER_UNSAFE`](/errors/X_CATCH_RENDER_UNSAFE) | a `catch` binding is rendered into a refusal by a form that can itself throw |
| [`X_CATCH_RENDER_PIN_STALE`](/errors/X_CATCH_RENDER_PIN_STALE) | a package's unsafe-catch pin is above what the tree contains |
| [`X_CATCH_RENDER_UNSCANNED`](/errors/X_CATCH_RENDER_UNSCANNED) | the unsafe-catch scan read no source file |
| [`X_CONFIG_KEY_UNREAD`](/errors/X_CONFIG_KEY_UNREAD) | `AppConfig` declares a key nothing in `packages/*/src` reads |
| [`X_CONFIG_READER_PIN_STALE`](/errors/X_CONFIG_READER_PIN_STALE) | a pinned config key gained a reader |
| [`X_CONFIG_READERS_UNSCANNED`](/errors/X_CONFIG_READERS_UNSCANNED) | the config-reader scan matched no interface or no source |
| [`X_DECLARED_KEY_UNREAD`](/errors/X_DECLARED_KEY_UNREAD) | a leaf key of a **declaration surface** — the type a primitive or a `define*` factory takes — is read by nothing in `packages/*/src` |
| [`X_DECLARATION_READER_PIN_STALE`](/errors/X_DECLARATION_READER_PIN_STALE) | a pin in that ratchet no longer holds |
| [`X_DECLARATION_READERS_UNSCANNED`](/errors/X_DECLARATION_READERS_UNSCANNED) | the declaration scan walked nothing |
| [`X_DOC_MIGRATION_SECTION_MISSING`](/errors/X_DOC_MIGRATION_SECTION_MISSING) | a released major has a summary row in `wiki/Upgrading.md` and no `→ X.Y.Z, entry by entry` section for it to point at |
| [`X_DOC_CONFIG_KEY_UNKNOWN`](/errors/X_DOC_CONFIG_KEY_UNKNOWN) | a page tells a reader to set a key `AppConfig` does not declare |
| [`X_DOC_CONFIG_ALLOWANCE_STALE`](/errors/X_DOC_CONFIG_ALLOWANCE_STALE) | an entry in `DOC_CONFIG_KEY_ALLOWANCES` matches nothing in the tree |
| [`X_DOC_COMMAND_PIN_EXCEEDED`](/errors/X_DOC_COMMAND_PIN_EXCEEDED) | a page holds more unresolved `x` citations than its pin |
| [`X_TIER_FLOOR_UNDECLARED`](/errors/X_TIER_FLOOR_UNDECLARED) | a package sits above the lowest tier its own imports allow, with no written reason |
| [`X_TIER_FLOOR_STALE`](/errors/X_TIER_FLOOR_STALE) | `FLOOR_ABOVE` keeps a row for a package that is at its floor, or names no package at all |
| [`X_SCAFFOLD_VERIFY_UNREADABLE`](/errors/X_SCAFFOLD_VERIFY_UNREADABLE) | `x verify --json` in a scaffolded app printed no step table this gate could parse |
| [`X_GATE_CODE_UNDOCUMENTED`](/errors/X_GATE_CODE_UNDOCUMENTED) | a code the never-ships list names has no table row, or a code `scripts/` declares is missing from that list |
| [`X_GATE_CODE_BACKLOG_STALE`](/errors/X_GATE_CODE_BACKLOG_STALE) | a code pinned in `scripts/gate-codes-backlog.ts` that this page is no longer wrong about |
| [`X_SIDE_EFFECTS_UNDECLARED`](/errors/X_SIDE_EFFECTS_UNDECLARED) | a module runs a statement at import time and its package's `sideEffects` excludes it |
| [`X_SIDE_EFFECTS_BY_USE_STALE`](/errors/X_SIDE_EFFECTS_BY_USE_STALE) | a `SIDE_EFFECTS_BY_USE` row that no longer holds |
| [`X_SIDE_EFFECTS_UNANCHORED`](/errors/X_SIDE_EFFECTS_UNANCHORED) | a module on `SIDE_EFFECTS_ANCHORS` that no entry imports for effect |
| [`X_SIDE_EFFECTS_ANCHOR_STALE`](/errors/X_SIDE_EFFECTS_ANCHOR_STALE) | a `SIDE_EFFECTS_ANCHORS` row naming a module nothing declares |
| [`X_SIDE_EFFECTS_ENTRY_STALE`](/errors/X_SIDE_EFFECTS_ENTRY_STALE) | a declared `sideEffects` entry matches no file in the package |
| [`X_SIDE_EFFECTS_MISSING`](/errors/X_SIDE_EFFECTS_MISSING) | a package declares no `sideEffects` at all |
| [`X_SIDE_EFFECTS_PIN_STALE`](/errors/X_SIDE_EFFECTS_PIN_STALE) | a package pinned as declaring no `sideEffects` now declares one |
| [`X_SIDE_EFFECTS_UNSCANNED`](/errors/X_SIDE_EFFECTS_UNSCANNED) | the scan walked no package, or found no import-time effect anywhere |
| [`X_CONFIG_KEY_READER_AMBIGUOUS`](/errors/X_CONFIG_KEY_READER_AMBIGUOUS) | an `AppConfig` leaf key's only "readers" are files matching its **bare** name, none of them in the section's own package and none spelling the qualified `<section>.<key>` |
| [`X_PROTO_CHAIN_INDEX`](/errors/X_PROTO_CHAIN_INDEX) | a plain object literal typed `Record<…>` is READ with a computed key that is not a string literal |
| [`X_PROTO_CHAIN_INDEX_PIN_STALE`](/errors/X_PROTO_CHAIN_INDEX_PIN_STALE) | a package is pinned above the number of prototype-reachable reads it still has |
| [`X_PROTO_CHAIN_INDEX_UNSCANNED`](/errors/X_PROTO_CHAIN_INDEX_UNSCANNED) | the scan read no source file |
| [`X_FLIGHT_SECOND_CURVE`](/errors/X_FLIGHT_SECOND_CURVE) | a module other than `packages/core/src/backoff.ts` computes its own backoff |
| [`X_NOT_IMPLEMENTED_COPY`](/errors/X_NOT_IMPLEMENTED_COPY) | a package other than `@ultimat3/core` constructs `X_NOT_IMPLEMENTED` itself |
| [`X_NOT_IMPLEMENTED_COPY_UNSCANNED`](/errors/X_NOT_IMPLEMENTED_COPY_UNSCANNED) | the rule found no construction of `X_NOT_IMPLEMENTED` anywhere, core's own included |
| [`X_FLIGHT_RANDOM_UNINJECTED`](/errors/X_FLIGHT_RANDOM_UNINJECTED) | a shipped source file calls `Math.random()` |
| [`X_HELPER_COPY`](/errors/X_HELPER_COPY) | shipped source carries a second implementation of a helper that has one home |
| [`X_FINITE_BOUND_UNCHECKED`](/errors/X_FINITE_BOUND_UNCHECKED) | a numeric option is defaulted with `??` and never checked for finiteness |
| [`X_FINITE_BOUND_PIN_STALE`](/errors/X_FINITE_BOUND_PIN_STALE) | a package is pinned above the number of unchecked numeric options it still has |
| [`X_FINITE_BOUND_UNSCANNED`](/errors/X_FINITE_BOUND_UNSCANNED) | the scan read no source file |
| [`X_DEAD_DOCS_HOST`](/errors/X_DEAD_DOCS_HOST) | a shipped source file builds a URL on `ultimate.dev` |
| [`X_DEAD_DOCS_HOST_PIN_STALE`](/errors/X_DEAD_DOCS_HOST_PIN_STALE) | a package is pinned above the number of dead-host URLs it still has |
| [`X_DEAD_DOCS_HOST_UNSCANNED`](/errors/X_DEAD_DOCS_HOST_UNSCANNED) | the scan read no source file |
| [`X_SECRET_COMPARED_UNSAFELY`](/errors/X_SECRET_COMPARED_UNSAFELY) | a value whose **name** says it is a secret is compared with `===`, `!==`, `.includes()`, `.equals()` or `Buffer.compare()` |
| [`X_SECRET_COMPARE_PIN_STALE`](/errors/X_SECRET_COMPARE_PIN_STALE) | a package is pinned above the number of secret-named comparisons it still has |
| [`X_SECRET_COMPARE_UNSCANNED`](/errors/X_SECRET_COMPARE_UNSCANNED) | the scan read no source file |
| [`X_VERSION_STAMP_PIN_STALE`](/errors/X_VERSION_STAMP_PIN_STALE) | a page is pinned as naming a version for a reason that is not a stamp, and the page no longer says it |
| [`X_WORKSPACE_MANIFEST_UNREADABLE`](/errors/X_WORKSPACE_MANIFEST_UNREADABLE) | a `package.json` the workspace glob matched cannot be read as a workspace manifest |
| [`X_APP_NAME_EMPTY`](/errors/X_APP_NAME_EMPTY) | the app name has no letters or digits |
| [`X_APP_EMPTY`](/errors/X_APP_EMPTY) | an app with an app.config.ts registered no primitive |
| [`X_BOUNDARY_SURFACE_IMPORT`](/errors/X_BOUNDARY_SURFACE_IMPORT) | a surface imports one SURFACE_SPECS does not allow |
| [`X_PERMISSION_UNGRANTED`](/errors/X_PERMISSION_UNGRANTED) | an action, query or route requires a permission no role grants |
| [`X_JOB_UNREGISTERED`](/errors/X_JOB_UNREGISTERED) | a job reached the manifest under its positional anonymous name |
| [`X_FEATURE_UNKNOWN`](/errors/X_FEATURE_UNKNOWN) | x g --feature names a slice that does not exist |
| [`X_ROUTE_ASYNC_PAGE`](/errors/X_ROUTE_ASYNC_PAGE) | a route exports an async Page |
| [`X_BUDGET_PARAMS_UNDECLARED`](/errors/X_BUDGET_PARAMS_UNDECLARED) | a dynamic route with a budget declares no prerender() paths to weigh it by |
| [`X_TEST_BUDGET_INVALID`](/errors/X_TEST_BUDGET_INVALID) | a test memory budget or worker cap env var does not parse |
| [`X_VERIFY_SHARD_INVALID`](/errors/X_VERIFY_SHARD_INVALID) | x verify --shard was given a spec or a step list it cannot split |
| [`X_VERIFY_MERGE_INCOMPLETE`](/errors/X_VERIFY_MERGE_INCOMPLETE) | x verify merge was handed parts that do not add up to the whole gate |
| [`X_VERIFY_MERGE_INPUT`](/errors/X_VERIFY_MERGE_INPUT) | a part handed to x verify merge is not an x verify --json document |
| [`X_SITEMAP_EXTRA_INVALID`](/errors/X_SITEMAP_EXTRA_INVALID) | a seo.sitemap.extra path names no public page |
| [`X_DEV_RESTART_REQUIRED`](/errors/X_DEV_RESTART_REQUIRED) | a save reached a module that defines a primitive; only a new process serves it |
| [`X_DEV_ROOT_GONE`](/errors/X_DEV_ROOT_GONE) | the app root x dev serves was deleted or moved |
| [`X_VERIFY_STEP_TIMEOUT`](/errors/X_VERIFY_STEP_TIMEOUT) | a gate step ran past its deadline and was stopped |
| [`X_COVERAGE_BELOW_FLOOR`](/errors/X_COVERAGE_BELOW_FLOOR) | the unit suite covers less of the app than x.verify.json states |
| [`X_COVERAGE_FLOOR_UNSTATED`](/errors/X_COVERAGE_FLOOR_UNSTATED) | x.verify.json states no coverage floor, or one under 95 with no reason |
| [`X_COVERAGE_FLOOR_STALE`](/errors/X_COVERAGE_FLOOR_STALE) | the app now covers more than the floor in x.verify.json states |
| [`X_DB_HANDLE_UNREGISTERED`](/errors/X_DB_HANDLE_UNREGISTERED) | an entity x g wrote is not in the app's typed database handle |
| [`X_ROLE_LOAD_INCOMPLETE`](/errors/X_ROLE_LOAD_INCOMPLETE) | a worker or scheduler did not register a job or task the manifest names |
| [`X_ADMIN_RESOURCE_UNWIRED`](/errors/X_ADMIN_RESOURCE_UNWIRED) | an admin override x g wrote is not in the app's defineAdmin() call |
| [`X_IMAGE_NOT_PREBUILT`](/errors/X_IMAGE_NOT_PREBUILT) | a container role built at boot what the image build should have: island chunks or stylesheets |
| [`X_ADMIN_UNSCANNED`](/errors/X_ADMIN_UNSCANNED) | a defineAdmin() declaration sits outside the app scan, so the admin is never mounted |
| [`X_FRAMEWORK_TABLE_ORPHANED`](/errors/X_FRAMEWORK_TABLE_ORPHANED) | a framework table no release reads any more is still in the database |
| [`X_BUILD_OUT_UNSAFE`](/errors/X_BUILD_OUT_UNSAFE) | the static export directory is not one a build may empty |
| [`X_FRAMEWORK_SCHEMA_UNAPPLIED`](/errors/X_FRAMEWORK_SCHEMA_UNAPPLIED) | a serving role booted over a database whose framework schema this build never applied |
| [`X_APP_URL_PORT_MISMATCH`](/errors/X_APP_URL_PORT_MISMATCH) | APP_URL names a loopback port x dev does not serve |
| [`X_DEV_HOST_REFUSED`](/errors/X_DEV_HOST_REFUSED) | a /_x request named a host that is not this machine |
| [`X_TRUSTED_PROXY_HOPS_INVALID`](/errors/X_TRUSTED_PROXY_HOPS_INVALID) | TRUSTED_PROXY_HOPS is not a whole number of proxies the boot accepts |
| [`X_PERMISSION_BORROWED`](/errors/X_PERMISSION_BORROWED) | an app rule requires a permission only an imported package declared |
| [`X_ERROR_CODE_UNTHROWN_STALE`](/errors/X_ERROR_CODE_UNTHROWN_STALE) | a code UNTHROWN_CODES lists as thrown by nothing is thrown again — delete it from UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts |
| [`X_DEV_STATE_UNWRITABLE`](/errors/X_DEV_STATE_UNWRITABLE) | x dev cannot claim its state directory |
| [`X_PACKAGE_TEST_ONLY_SHIPPED`](/errors/X_PACKAGE_TEST_ONLY_SHIPPED) | a test-only module ships in the tarball |
| [`X_ISLAND_MODULE_DUPLICATED`](/errors/X_ISLAND_MODULE_DUPLICATED) | An island chunk bundles one module more than once |
| [`X_BACKFILL_SLICE_ENTITY`](/errors/X_BACKFILL_SLICE_ENTITY) | the slice holds no entity a generated backfill can sweep |
| [`X_LAYOUT_SIBLING_MODULE`](/errors/X_LAYOUT_SIBLING_MODULE) | a primitive module beside its directory |
| [`X_SLICE_POLICY_INCOMPLETE`](/errors/X_SLICE_POLICY_INCOMPLETE) | a generator needs an export the slice policy.ts does not declare |
| [`X_WORKER_QUEUE_UNKNOWN`](/errors/X_WORKER_QUEUE_UNKNOWN) | WORKER_QUEUES names a queue no job and no jobs.queues entry declares |
| [`X_UPGRADE_DIRTY_TREE`](/errors/X_UPGRADE_DIRTY_TREE) | x upgrade refused a tree with uncommitted changes |
| [`X_UPGRADE_MIXED_PINS`](/errors/X_UPGRADE_MIXED_PINS) | x upgrade found two @ultimat3/* versions across the workspaces |
| [`X_UPGRADE_HOP_TOO_WIDE`](/errors/X_UPGRADE_HOP_TOO_WIDE) | x upgrade --to is outside the one hop a run may make |
| [`X_UPGRADE_REGISTRY_UNREACHABLE`](/errors/X_UPGRADE_REGISTRY_UNREACHABLE) | x upgrade could not read the published versions from npm |
| [`X_UPGRADE_PIN_UNREADABLE`](/errors/X_UPGRADE_PIN_UNREADABLE) | x upgrade found an @ultimat3/* dependency that names no version |
| [`X_UPGRADE_VERSION_UNPUBLISHED`](/errors/X_UPGRADE_VERSION_UNPUBLISHED) | x upgrade --to names a version npm does not have |
| [`X_UPGRADE_INSTALL_FAILED`](/errors/X_UPGRADE_INSTALL_FAILED) | bun install failed after x upgrade wrote the pins |
| [`X_UPGRADE_GATE_UNREADABLE`](/errors/X_UPGRADE_GATE_UNREADABLE) | the installed x verify answered with no JSON report |
| [`X_DEPLOY_BUILD_UNSTAMPED`](/errors/X_DEPLOY_BUILD_UNSTAMPED) | the deployment answers with no build header |
| [`X_DEPLOY_UNSTABLE`](/errors/X_DEPLOY_UNSTABLE) | the build answered but did not hold |
| [`X_DEPLOY_QUEUE_UNSERVED`](/errors/X_DEPLOY_QUEUE_UNSERVED) | a registered queue has no serving worker of this build |
| [`X_DEPLOY_BUILD_MISMATCH`](/errors/X_DEPLOY_BUILD_MISMATCH) | production never served this build |
| [`X_JOB_OUTLASTS_DRAIN`](/errors/X_JOB_OUTLASTS_DRAIN) | a job's declared timeout outlasts the worker's budget |
| [`X_FEATURE_REQUIRED`](/errors/X_FEATURE_REQUIRED) | x g query or x g backfill named no slice to read |
| [`X_BOUNDARY_PACKAGE_TO_APP`](/errors/X_BOUNDARY_PACKAGE_TO_APP) | packages/ imported apps/ at runtime |
| [`X_APP_IMPORT_UNRESOLVED`](/errors/X_APP_IMPORT_UNRESOLVED) | an app module imports what does not resolve |
| [`X_STREAM_ALREADY_FLUSHED`](/errors/X_STREAM_ALREADY_FLUSHED) | a response header was written after the stream flushed |
| [`X_QUERY_SLICE_ENTITY`](/errors/X_QUERY_SLICE_ENTITY) | x g query into a slice whose entity is not the one it scaffolds |
| [`X_DEPLOY_ENV_MISSING`](/errors/X_DEPLOY_ENV_MISSING) | x deploy --method compose found no complete .env.production |
| [`X_ENV_FILE_EXISTS`](/errors/X_ENV_FILE_EXISTS) | x env init --production found .env.production already written |
| [`X_DEV_STOP_TIMEOUT`](/errors/X_DEV_STOP_TIMEOUT) | x stop sent SIGTERM and x dev did not exit in time |
| [`X_DEV_STOP_DENIED`](/errors/X_DEV_STOP_DENIED) | x stop may not signal the x dev the lock names |
| [`X_ASSET_RETAIN_FAILED`](/errors/X_ASSET_RETAIN_FAILED) | Build assets were not retained |
| [`X_APP_MODULE_LOAD_FAILED`](/errors/X_APP_MODULE_LOAD_FAILED) | an app module failed to load, so the role refused to serve a partial app |
| [`X_CHART_MISSING`](/errors/X_CHART_MISSING) | x g chart-alerts found no Helm chart to write into |
| [`X_ENTITY_VIEW_DRIFT`](/errors/X_ENTITY_VIEW_DRIFT) | a view entity's columns disagree with the view its migration created |
| [`X_CLIENT_SPEC_UNSUPPORTED`](/errors/X_CLIENT_SPEC_UNSUPPORTED) | x client met an OpenAPI construct its compiler refuses |
| [`X_CLIENT_STALE`](/errors/X_CLIENT_STALE) | a generated client is older than the document it was compiled from |
| [`X_CLIENT_EDITED`](/errors/X_CLIENT_EDITED) | a generated client file was changed by hand |
| [`X_GRAPH_NODE_UNKNOWN`](/errors/X_GRAPH_NODE_UNKNOWN) | x graph or x impact was asked about a node the app graph does not hold |
| [`X_CLIENT_SPEC_INVALID`](/errors/X_CLIENT_SPEC_INVALID) | x client was handed a document that is not OpenAPI 3.0 or 3.1 |
| [`X_REPRO_UNKNOWN`](/errors/X_REPRO_UNKNOWN) | x repro was given an id nothing holds |
| [`X_REPRO_NOT_REPRODUCED`](/errors/X_REPRO_NOT_REPRODUCED) | a written repro test did not fail the way the original did |
| [`X_REPRO_CAPTURE_OFF`](/errors/X_REPRO_CAPTURE_OFF) | x repro was given a request id while failure capture is off |
| [`X_ENTITY_RETAIN_UNSWEPT`](/errors/X_ENTITY_RETAIN_UNSWEPT) | an entity declares retain and no purge() sweeps it |
| [`X_NEW_SHAPE_UNKNOWN`](/errors/X_NEW_SHAPE_UNKNOWN) | x new --shape names no registered shape |
| [`X_NEW_SHAPE_CONFLICT`](/errors/X_NEW_SHAPE_CONFLICT) | x new --shape with --no-example |
| [`X_SEO_CARD_ROUTE_UNKNOWN`](/errors/X_SEO_CARD_ROUTE_UNKNOWN) | og.capture names a path no site/ route answers |
| [`X_SEO_CARD_BROWSER_MISSING`](/errors/X_SEO_CARD_BROWSER_MISSING) | a static build with social cards found no browser to photograph them |
| [`X_IMAGE_SOURCE_UNREADABLE`](/errors/X_IMAGE_SOURCE_UNREADABLE) | a responsiveImage src is not a file the static export holds |
| [`X_VERIFY_SKIPS_OVER_CEILING`](/errors/X_VERIFY_SKIPS_OVER_CEILING) | a step skipped more tests than its skipCeiling allows |
| [`X_ASSET_VARIANT_UNDECLARED`](/errors/X_ASSET_VARIANT_UNDECLARED) | an /assets image variant responsiveImage() never mints |
| [`X_NEW_SHAPE_GENERATE_FAILED`](/errors/X_NEW_SHAPE_GENERATE_FAILED) | a shape generator failed in the new app |
| [`X_ISLAND_DISPOSER_MISSING`](/errors/X_ISLAND_DISPOSER_MISSING) | an island's mount returns no disposer |
| [`X_SOCKET_HAND_ROLLED`](/errors/X_SOCKET_HAND_ROLLED) | an app upgrades a websocket itself |
| [`X_EXERCISE_FILE_UNEDITABLE`](/errors/X_EXERCISE_FILE_UNEDITABLE) | x g could not add an entry to apps/web/exercise.ts |
| [`X_ERROR_REPORTER_DSN_UNCLAIMED`](/errors/X_ERROR_REPORTER_DSN_UNCLAIMED) | SENTRY_DSN is set, and the app installed a reporter marked neither as its Sentry transport nor as a local sink |
| [`X_BOUNDARY_ADAPTER_IMPORT`](/errors/X_BOUNDARY_ADAPTER_IMPORT) | an app module imports an adapter installer |
| [`X_PREBUILT_REGISTRY_STALE`](/errors/X_PREBUILT_REGISTRY_STALE) | the image's prebuilt module registry does not list the app's modules, so the role scanned instead |
| [`X_APP_ROOT_NESTED`](/errors/X_APP_ROOT_NESTED) | a second app.config.ts inside the app |
| [`X_WORKSPACE_NAME_TAKEN`](/errors/X_WORKSPACE_NAME_TAKEN) | x g app or x g package was given a name the other workspace kind already holds |
| [`X_PARTITIONS_UNMAINTAINED`](/errors/X_PARTITIONS_UNMAINTAINED) | a partitioned entity with no partitions() job |
| [`X_BOUNDARY_LOADER_IMPORT`](/errors/X_BOUNDARY_LOADER_IMPORT) | an app module imports a registration loader |
| [`X_WORKSPACE_EXTERNAL_DEP_UNDECLARED`](/errors/X_WORKSPACE_EXTERNAL_DEP_UNDECLARED) | a workspace imports a registry package that neither it nor the app root declares |
| [`X_TYPESCRIPT_VERSION`](/errors/X_TYPESCRIPT_VERSION) | The app declares a TypeScript older than the one x new scaffolds |

## Reserved codes

Everything above this heading is live: `x errors explain <CODE>` answers for it today, and the `errors` step fails the build if it does not (`X_ERROR_CODE_UNREGISTERED`). Everything below is documented for a different reason and is deliberately outside that rule.

### Not thrown yet

Reserved, not registered. The name is spoken for — the design docs use it and no future code may reuse it — but nothing raises it in this build, so `x errors explain` refuses it. The right-hand column is what actually happens today.

| Reserved code | What happens today |
|---|---|
| `X_SW_HAND_EDITED` | `sw.js` carries no checksum, so a hand edit survives `x build` and is silently overwritten on the next one |
| `X_SW_UNCACHEABLE` | an `offline` strategy contradicting the route's `render` mode is accepted; `X_SW_SCOPE_INVALID` covers only the scope half |
| `X_CACHE_UNTAGGED_QUERY` | a query no tag covers is cached and never invalidated. `X_CACHE_TAG_UNKNOWN` catches the opposite mistake — a tag no entity declared |

New codes are added in the owning package's `src/errors.ts` and registered through `registerErrorCodes()`; add the row here in the same pull request, or the `errors` step of `x verify` fails the build with `X_ERROR_CODE_UNDOCUMENTED` — see [Contributing](/contributing).