Skip to content

Error Codes http

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/http

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

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

Clone this wiki locally