Skip to content

Error Codes auth

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

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

Notes

Auth and sessions

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.

Clone this wiki locally