Repository navigation
Error Codes core
Part of Error codes: every code @ultimat3/core registers. x errors explain <CODE> --json prints the same row.
| 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 |
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_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_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_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_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_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 |
encodeRecordEnvelope() from @ultimat3/core — build the body with it 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_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_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_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_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_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 |
after: null — drop the cursor and request the first page |
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_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_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_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_ERROR_CODE_DUPLICATE |
error code registered twice | two packages declared the same code |
git grep -n <CODE> — rename the colliding code in the registering package's src/errors.ts
|
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_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_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_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_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 |
flightGate({ maxConcurrent, maxQueued }) widened at the call site — only if the box has the capacity the extra slots buy — or retry after the Retry-After header |
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_ID_INVALID |
value is not a valid id | a hand-built string passed where a typed id is required |
uuidV7() / typedId<'post'>() from @ultimat3/core — generate ids with them |
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_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 |
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 |
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_INTERNAL |
unexpected internal framework error | a non-Ultimate error escaped into framework code; also the sync node's ack for a throw with no code, whose cause is withheld from the socket and sent to the error reporter | 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_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) |
resetLifecycle() from @ultimat3/core, in a test, between the drain and the next start(). In a process, start every role BEFORE the first drain — a drained process is on its way out and is replaced, never reused |
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 |
Intl.DateTimeFormat.supportedLocalesOf([tag]) screens header input — pass en, en-GB, de-DE
|
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 |
{ maxSeries: 4000 } in the declaration, raised deliberately: counter('orders_total', { maxSeries: 4000 }) — or drop the unbounded label from the call site |
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_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_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_NO_CONTEXT |
no request context is active | framework code called outside the ALS context | runWithContext(ctxOf({ … }), fn) |
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 |
export 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 |
bun -e 'console.log(encodeURIComponent(process.argv[1]))' <value> prints <encoded>: set <the variable the cause names>=<key>=<encoded> — 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 |
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 — the collector's HTTP receiver; unsetting OTEL_EXPORTER_OTLP_PROTOCOL works too |
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_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_PROXY_INVALID |
an outbound HTTP call was given a proxy it cannot use | proxy is not an http:/https: URL, or its resolver threw | outbound({ url, vendor, dial, proxy: 'http://<user>:<password>@<proxy-host>:<port>' }) |
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_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_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_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_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_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_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_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_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 |
registerReadinessCheck('<name>-replica', check) — name the second check for what it actually probes; or hold the unregister the first registration returned and call it first |
X_REDACT_PATTERN_UNSAFE |
a redactValues() pattern is refused at registration | a value-redaction pattern has no g flag, is sticky, matches the empty string, or nests an unbounded quantifier inside an unbounded-quantified group — it would leak a second match, miss mid-value matches, splice into every value, or backtrack exponentially on a log line | in the redactValues([...]) call, give the pattern the g flag, drop y, require at least one character, and unnest the quantifier (write (?:a+)+ as a+) |
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_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_ROLE_INVALID |
ROLE is not a known runtime role |
typo or an old role name in the env |
export ROLE=web — or sync, worker, scheduler, migrate, replicator
|
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_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_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_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_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_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_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_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_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_SERVICE_DUPLICATE |
a service name is registered twice | two defineService('name', ...) calls used the same name |
git grep -n defineService — two declarations share the name: rename one of them |
X_SERVICE_MISSING |
service is not registered on the request context |
ctx.<service> used without providing it |
pass it in ctxOf({ services: { … } })
|
X_SHUTDOWN_TIMEOUT |
graceful shutdown exceeded its deadline | an in-flight handler outlived DRAIN_TIMEOUT
|
drain: { deadlineMs: 600_000 } in app.config.ts (configureLifecycle({ deadlineMs }) outside a framework boot) — or shorten the slow handler |
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 |
fence.generation() — discard this answer and re-issue the work against it; whoever called bump() has already started the replacement |
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 |
export OTEL_TRACES_SAMPLER_ARG=0.05 — the cause names the spelling it read |
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_UNREACHABLE |
unreachable branch was reached | an exhaustive switch met a value the type says cannot exist |
narrow the union at the call site |
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.
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.
Ultimate — v31.44.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