Skip to content

Error Codes action

github-actions[bot] edited this page Nov 17, 2026 · 3 revisions

Error codes: @ultimat3/action

Part of Error codes: every code @ultimat3/action registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
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 deprecated: { <field>: '2026-12-31T23:59:59Z' } on the action — an ISO-8601 instant
X_ACTION_DUPLICATE two actions registered under one name duplicate export names across features x actions list --json — names are global: rename one of the two exports
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 export const name = action({ input, output, policy, handle }) — action() from @ultimat3/action
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_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 defineApi({ http: { pathStyle } }) — import its module (apps/web/api/index.ts) before the one that derives a path; or derive the path where it is used — inside the component or function, never in a module-level const
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 x actions list --json prints every derived route — rename one export so the two derive different paths
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_ACTION_POLICY_MISSING an action was registered without a policy build-time check on the action registry policy: can('<resource>:<verb>') in the declaration — a permission your definePermissions() call declares, never the action's own name — or policy: allow('public') when the operation is genuinely public (allow() takes a label, never a permission)
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_ACTION_UNREGISTERED an action was projected before it was registered, so it has no name .client() / .job() / .openapi() on an action no defineApi() named defineApi({ actions }) in apps/<app>/api/index.ts, listing the action's module — the boot names it before mounting routes
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_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_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_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: location.reload() — picks up the new client bundle. 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_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_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_IDEMPOTENCY_CONFLICT idempotency key reused with a different payload, or still in flight a retried request mutated its body { idempotencyKey: crypto.randomUUID() } — a fresh Idempotency-Key for a different payload; otherwise resend with the same key ({ idempotencyKey }) 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 { idempotencyKey: crypto.randomUUID() } on the client, one per request — or omit the header 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_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_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 x logs tail --json in dev, your log index elsewhere: find the first attempt, fix its cause, then send a fresh Idempotency-Key
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 { idempotencyKey } — resend with the same Idempotency-Key: the attempt that took the key over answers it, and this one's transaction was rolled back
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_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_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_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_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
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 conflict: 'server-wins' — or add updatedAt (a number, epoch ms, written by the server) to the entity. With no entity row in the output: conflict: 'server-wins', or return the entity row from the mutator's output
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 idempotent: true in the mutator definition
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_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_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 isUltimateError(e) && e.code === 'X_CLIENT_TRANSPORT_FAILED' — match X_CLIENT_TRANSPORT_FAILED instead, with isUltimateError from @ultimat3/core

Notes

Actions

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

Clone this wiki locally