Repository navigation
Error Codes auth
Part of Error codes: every code @ultimat3/auth registers. x errors explain <CODE> --json prints the same row.
| Code | Means | Typical cause | Fix |
|---|---|---|---|
X_ACCOUNT_LOCKED |
per-ip, per-account or per-org bucket is inside its lockout | repeated failed attempts — password or second-factor code. cause names the caller's own key (an address or an email) and the seconds left; a locked org is never named, because its id was looked up from the address the caller typed. The wiki used to name x auth unlock <key>, a command that has never existed |
await auth.limiter.recordSuccess('<key>') clears this one bucket (await auth.orgLimiter.recordSuccess(orgKey(user.orgId)) for a tenant) — or wait out the seconds cause names, or raise defineAuth({ rateLimit }). Never reset(): it drops every bucket in the table, including the spray this lockout is holding |
X_API_KEY_INVALID |
key unknown, revoked, expired, wrong, or owned by a user who is gone or disabled | one shape for all of them — a precise message is an enumeration oracle, so which it was is not named here and never will be. The wiki used to name x auth keys list --json, a command that has never existed |
const { plaintext, record } = issueApiKey({ env, scopes }); await auth.adapter.putApiKey(record) — issue a replacement; auth.adapter.listApiKeys(ownerId) through describeApiKey() shows which keys are still live |
X_AUTH_CLIENT_INVALID |
an oauth client was registered with a list value the store cannot hold as one value | registerClient() was handed a redirect uri, grant type, scope or resource that is empty or has whitespace inside; the store keeps each list as space-joined text |
server.registerClient({ name, <field>: ['<one value per element>'] }) — the field the cause names, split into its values |
X_AUTH_CONSENT_INVALID |
a consent was approved for a request the authorization server refuses | approve() or deny() was handed a request readRequest(url) would refuse — an unknown client, an unregistered redirect, a scope the client never asked for | server.readRequest(url) # on the consent page: render its refusal, approve only what it returned |
X_AUTH_GRANT_DISABLED |
a token request named a grant this authorization server does not enable | the client posted a grant_type that is not in authorizationServer({ grants }) | authorizationServer({ grants: ['authorization_code', 'refresh_token', '<grant>'] }) # with its lifetime |
X_AUTH_LIMITER_NOT_SHARED |
the app declared a fleet-wide credential throttle and the limiter keeps its counters per process |
defineAuth({ rateLimit: { scope: 'shared' } }) against the built-in limiter, whose scope is 'process' — account lockout would be maxAttempts × replicas, and a lockout on one replica invisible to the others. Refused at defineAuth, never at a request |
pass a shared AuthLimiter to defineAuth({ limiter }), or drop to scope: 'process'
|
X_AUTH_LIMITER_POLICY_MISMATCH |
a custom credential limiter enforces different numbers than the app declared |
defineAuth({ limiter }) where the limiter's own policy disagrees with the declared rateLimit on maxAttempts, windowMs or lockoutMs. Auth.rateLimit is what an operator reads as "what this deployment enforces", and an injected limiter could leave nothing behind it. The cause names both numbers and says which half is likely wrong; maxKeys is deliberately not compared, since it bounds one process' table and a shared limiter has no opinion on it |
{ <field>: <declared> } in the policy the limiter is constructed with — the declaration is what Auth.rateLimit reports, so it is the half that stays. If the limiter's number is the one this deployment means, change the declaration instead; meta carries { field, declared, enforced }
|
X_AUTH_SERVER_INVALID |
the authorization server was configured with a field it cannot run on | authorizationServer() was handed a bad issuer, consentPath or lifetimes, or a grant was named without the lifetime, path or store method it needs | authorizationServer({ <field>: … }) # the field the cause names |
X_AUTH_SIGN_IN_UNCONFIGURED |
a people-facing role started with no sign-in settings outside development and test | x g sign-in wrote a boot guard, and a web or sync role started with the sign-in env keys unset |
export <KEY>="<value>" for every unset key the cause names — in the role's deployed environment (compose environment:, the platform's secrets), then restart the role |
X_AUTH_WRITE_FAILED |
an adapter write returned no row, so it cannot be confirmed | an insert … returning * wrote nothing — the table is missing its migration, or a trigger or RLS policy swallowed the row. Also a write one of x_users' own unique constraints refused — a second row at one email, external_id or id, on createUser or updateUser; meta.column names which, and memoryAuthAdapter() and postgresAuthAdapter() answer the same code (As of 2026-10; Postgres answered X_DB_UNIQUE_VIOLATION before). Also an OAuth sign-in whose updateUser returned no row for the provider-verified stamp (emailVerifiedNotStored; X_NOT_IMPLEMENTED before As of 2026-10) — the flow fails closed rather than sign in a user every later login reads as unverified. This page printed x db query until 1.2.0; the db subcommands are gen, migrate, reset, studio, branch and backfill
|
x db migrate, then confirm the table with psql "$DATABASE_URL" -c "select 1 from x_users limit 1"
|
X_IDENTITY_PROVIDER_UNKNOWN |
the URL named an identity provider the sso routes were not given | a sign-in link or the IdP ACS URL carries an id that no entry in identityProviderRoutes({ providers }) declares | add the provider to identityProviderRoutes({ providers: [...] }), or correct the id in the link and in the IdP ACS URL |
X_MFA_REQUIRED |
password proven, second factor outstanding | the user has TOTP enrolled, and login() / completeOAuthLogin() throw before any session is written. meta.challenge is a sealed, five-minute credential for the second leg — meta, never cause: both public surfaces publish cause and drop meta, so the sign-in handler decides how it travels |
catch X_MFA_REQUIRED in your sign-in handler, hand error.meta.challenge to the caller, and finish with await completeMfa(auth, challenge, code). No route ships. A wrong code is X_UNAUTHENTICATED and stays counted against the account, address and tenant buckets; past rateLimit.maxAttempts it is X_ACCOUNT_LOCKED. Sealing needs the app's master key — X_SEAL_KEY_MISSING without one |
X_MFA_SECRET_INVALID |
a TOTP secret that is not RFC 4648 base32, so it decodes to zero bytes |
enrolTotp is handed an imported secret outside the alphabet, or totpCode is called with one. verifyTotp does not throw it — an unreadable stored secret reads as a non-verdict there, the same rule verifyAgainst follows for a password hash Bun cannot read, so a login checking a broken row gets a credential refusal rather than a 500 |
const { secret } = enrolTotp(auth, { account: user.email }) — issue a fresh one and store it. An imported secret must be base32 (A-Z and 2-7; padding, spaces and dashes are ignored) and must decode to at least one byte. Zero bytes is not a decode that failed closed: an HMAC keyed with zero bytes is a valid HMAC, so every unreadable secret in the table used to verify against one shared code stream that needed no secret to compute |
X_MFA_SECRET_UNSEALED |
a stored totp secret is not sealed, so it is never read as one | x_users.mfa_secret holds a value written before second-factor secrets were sealed at rest (or written past saveTotpSecret); the framework does not read a plaintext secret, so that account cannot finish a second factor until the value is sealed | x auth seal-mfa --json |
X_OAUTH_DENIED |
the user or the provider declined the authorization |
error= on the callback redirect — nearly always the consent screen's Cancel. Split out of X_OAUTH_EXCHANGE_FAILED so the commonest non-success outcome of a login stops paging on-call as a 502 provider outage |
restart at GET /auth/sso/<provider> and approve the consent screen; nothing is wrong with the app |
X_OAUTH_EXCHANGE_FAILED |
the provider refused the exchange or returned no usable identity | wrong client secret, an unregistered redirect_uri, a spent code, or a missing scope. Also a discovery document that declares a different issuer than the one asked for, and a key set with no importable key (the cached keys are kept). Not the user pressing Cancel — that is X_OAUTH_DENIED
|
meta.stage is token or userinfo: for token, match <PROVIDER>_CLIENT_SECRET and the registered redirect_uri, then x doctor --json; for userinfo, restart at GET /auth/sso/<provider>
|
X_OAUTH_PROVIDER_DUPLICATE |
two oauth providers were registered under one id | two registerOAuthProvider calls claiming one id. Refused at boot rather than replacing silently, because the winner would be whichever module imported second — and it decides where every login for that id goes, including which issuers an id token may claim
|
grep -rn registerOAuthProvider apps packages — give one of the two registerOAuthProvider({ id: '<id>' }) calls a different id, or delete the duplicate; github and google are registered by @ultimat3/auth itself |
X_OAUTH_PROVIDER_UNKNOWN |
the URL named a provider this app has not enabled | the :provider segment is not a known provider, or is one but was left out of defineAuth({ providers }); also providerFor() reaching for an id nothing registered. One refusal for all of them: distinguishing them would describe the app's configuration to an anonymous caller |
registerOAuthProvider({ id: '<id>' }) if it is not built in, then add that id to defineAuth({ providers: [...] }) — the registration comes first because a segment nothing registered cannot be added to providers at all, so "add it" alone was an instruction that could not be followed. The list the fix prints is what is known here, never the subset this app enabled, and meta carries only { provider }
|
X_OAUTH_STATE_INVALID |
state, nonce or PKCE verifier did not match | a replayed callback URL, a handshake that expired, or a token minted for another browser | restart the flow at GET /auth/sso/<provider> — a callback URL is single-use |
X_OAUTH_TOKEN_INVALID |
the id token failed its signature, issuer, audience or expiry check |
As of 2026-08 the signature is verified too, against the issuer's published key set through a JWKS client — until this cycle the token was decoded and its claims read, so a token minted by whoever posted it to the callback passed every check it faced. Also: a token that is not a three-segment JWT, a payload with no iss/sub/exp/aud, a client id in .env that is not the one the authorize URL was built with, or a skewed host clock |
the fix branches on which check failed — for a signature, confirm the token came from the provider's token URL and was not minted by the caller; for the rest, match <PROVIDER>_CLIENT_ID to the id beginOAuth() used, then restart at GET /auth/sso/<provider>
|
X_PASSKEY_CHALLENGE_EXPIRED |
a passkey ceremony named a challenge that is unknown, already used or past its ttl | the response was replayed, the options were issued by another ceremony, or the person took longer than the challenge ttl | x errors explain X_PASSKEY_CHALLENGE_EXPIRED --json, then fetch fresh options and run the ceremony once: await passkeys.loginOptions() |
X_PASSKEY_INVALID |
a passkey ceremony response failed its signature, origin, rp id, flag or counter check | the assertion or attestation was forged, tampered with, made for another origin or rp id, made without user verification, or came from a cloned authenticator whose signature counter went backwards | x errors explain X_PASSKEY_INVALID --json, then start the ceremony again: await passkeys.loginOptions() |
X_PASSKEY_STEP_UP_REQUIRED |
a sensitive action ran without a fresh user-verified passkey proof for its digest | the call carried no assertion, or the assertion approved other bytes than the ones this call would act on | x errors explain X_PASSKEY_STEP_UP_REQUIRED --json, then fetch stepUp.options({ userId, input }), run getPasskey(options) in the browser and resend the call with the response |
X_PASSWORD_WEAK |
strength check rejected the password | too short, or a known-common password |
defineAuth({ password: { minLength } }) to relax the policy — or choose a longer, uncommon password |
X_SAML_METADATA_INVALID |
saml IdP metadata has no entity id, HTTP-Redirect sign-on endpoint or signing certificate | the metadata XML was truncated, is SP metadata rather than IdP metadata, or names only an HTTP-POST sign-on endpoint | download the IdP metadata again from its federation metadata URL and pass the whole XML to samlIdentityProvider({ metadata }) |
X_SAML_RESPONSE_INVALID |
a saml response failed its signature, wrapping, audience, recipient, time, InResponseTo or replay check | the IdP signing certificate rotated, the SP entity id or ACS URL differs from what the IdP has configured, the clocks are skewed, or the response was tampered with or replayed | edit the samlIdentityProvider({ metadata, spEntityId, acsUrl }) call: paste the IdP current metadata XML and the entity id and ACS URL the IdP application is configured with |
X_SESSION_EXPIRED |
session passed its idle or absolute expiry |
cause names which of the two clocks ran out |
defineAuth({ session: { absoluteTtlMs: <ms> } }) (or idleTtlMs, whichever cause names) — or sign in again. The wiki used to name POST /auth/sign-in here; the framework mounts no such route, and the password half is the app's until it ships one |
X_UNAUTHENTICATED |
no authenticated actor for this request | the two things that produce an anonymous actor where one is needed: the request carried no __Host-x_session cookie, or it carried one nothing resolved. authenticate() answers the anonymous actor for a missing cookie rather than throwing, which is why the failure surfaces one layer later, at the surface that needed the actor. Also the code for an oauth identity a local account already holds — @ultimat3/auth owns it, @ultimat3/http only borrows it |
send the __Host-x_session cookie with this request, and resolve it once at the boundary: authenticate(auth, readSessionCookie(request, auth.sessions.policy))
|
X_VERIFICATION_PURPOSE_INVALID |
a verification purpose was declared twice or without a template | defineVerificationPurpose() was handed a name already declared, an empty name or no template | defineVerificationPurpose({ name: '<unique-name>', template: 'auth.<name>', ttlMs }) |
X_VERIFICATION_PURPOSE_UNKNOWN |
a verification token was issued or consumed for a purpose nothing declared | issueVerification or consumeVerification named a purpose no defineVerificationPurpose() call declared at boot | defineVerificationPurpose({ name: '<purpose>', template: 'auth.<purpose>', ttlMs }) # once, at boot |
GET /auth/sso/<provider> is the app's route to mount, not one the framework serves. Every OAuth fix above is reachable only where the host routes matching requests to oauthLogin(auth).start.handle; oauthLogin() supplies the descriptors and nothing else mounts them. The thrown fix: and the descriptor's path both read the one declaration in oauth-paths.ts, so the string cannot go stale — but As of 2026-08 serve.ts composes a fixed set of route tables with no seam for a raw Route, so nothing x new scaffolds mounts the pair and an app that has not mounted it itself answers that path with a 404.
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