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.

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"

{"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.

As of 2026-10 every code above 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 for symptom-first triage and CLI reference for the commands named in the fixes.

Core and runtime

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.

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.

Config and environment

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 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.

Schema and validation

HTTP

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.

Auth and sessions

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

Actions

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

Jobs

Backfills

Seven codes because each sends the reader somewhere different. Full walkthrough: Migrations and backfills.

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, 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.

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.

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.

Realtime

Cache

Storage

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.

Routes, render and budgets

SEO

PWA and build skew

i18n, money, time

Mail

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.

MCP and AI

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), 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:

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

Testing

UI

CLI and verify

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.

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.