Skip to content

Error Codes core

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

Error codes: @ultimat3/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

Notes

Metrics

Counter, gauge and histogram live in @ultimat3/core (metrics.ts), aggregate in process, and are read through one collectMetrics(). The wire format is a driver: MetricExporter is the seam, the default is a no-op, and metricsText() renders the Prometheus/OpenMetrics scrape body behind METRICS_PATH. An OTLP client ships As of 2026-08: otlpMetricExporter() and otlpSpanExporter() speak OTLP/HTTP JSON and read OTEL_EXPORTER_OTLP_ENDPOINT, with no new dependency. gRPC on :4317 is refused by design; scraping /metrics with an agent stays equally supported.

The three series docker/helm autoscales on are http_requests_total (the counter rps is derived from), connections and queue_demand — SCALING_METRICS in runtime-metrics.ts maps each ScalingSignal to its series, so the role table and the chart cannot drift apart.

Images

One pipeline in @ultimat3/core serves storage, seo and pwa. It decodes PNG, JPEG, WebP and GIF and encodes PNG, JPEG and WebP (DECODABLE_FORMATS / ENCODABLE_FORMATS, As of 2026-10); AVIF and SVG are identified and measured — enough to inline width/height and keep CLS at 0 — but never synthesised. A variant in one of those formats comes from a CDN or an ImageTransformDriver, never from a silent passthrough.

Clone this wiki locally