Repository navigation
Error Codes 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
|
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.
Ultimate — v31.43.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference