Repository navigation
Error Codes http
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
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 |
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