error codes

115 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

account_already_linked_to_different_user provider consideration: verify credentials

To prevent the account_already_linked_to_different_user error, if you changed provider projects/tenants, identifiers may differ; confirm you are linking the correct provider credentials for the environment.

account_already_linked_to_different_user debugging: verify environment

To debug the account_already_linked_to_different_user error, verify your app is connected to the expected database and environment (dev/staging/prod) to avoid confusion due to shared credentials or misconfigured environment variables.

account_already_linked_to_different_user provider consideration: request stable identifiers

To prevent the account_already_linked_to_different_user error, ensure you request stable user identifiers from the provider (e.g., OIDC openid scope) so accountId remains consistent across sessions.

account_already_linked_to_different_user error definition

The account_already_linked_to_different_user error occurs during the OAuth flow when attempting to link an OAuth provider account to the currently authenticated user, but that exact provider account is already linked to another user in the project. Better Auth blocks the link to prevent account takeover.

account_already_linked_to_different_user applies only to OAuth

The account_already_linked_to_different_user error is only triggered by OAuth flows (e.g., Google, GitHub, etc.). It is not triggered by email/password flows on their own.

account_already_linked_to_different_user resolution: unlink then link

To resolve the account_already_linked_to_different_user error, log in as the user who already has the provider linked, unlink the provider from that account, then link it to the intended account.

account_already_linked_to_different_user resolution: merge accounts

If both accounts belong to the same person and you want a single user, merge the accounts by choosing a primary user, moving sessions and linked accounts from the secondary user to the primary, then deactivating or deleting the secondary.

account_already_linked_to_different_user common cause: previous sign in

The account_already_linked_to_different_user error can occur because you previously signed in or signed up using this provider on a different user in the same project.

account_already_linked_to_different_user common cause: two local users

The account_already_linked_to_different_user error can occur when you have two local users (e.g., created via email/password or magic link), the provider was linked to one of them, and you are trying to link the same provider to the other.

account_already_linked_to_different_user common cause: shared environment credentials

The account_already_linked_to_different_user error can occur when test/preview environments share the same OAuth provider configuration and database, and the provider account is already linked to a different user record.

account_already_linked_to_different_user common cause: stale database links

The account_already_linked_to_different_user error can occur due to data migration or manual database edits that left a stale link pointing to the wrong user.

account_already_linked_to_different_user common cause: email matching vs provider identifier

The account_already_linked_to_different_user error can occur when linking relies on email matching to decide linking, but the actual unique key is the provider account identifier (providerId + accountId). If that mapping exists for another user, linking will be blocked.

account_already_linked_to_different_user prevention: avoid automatic linking

To prevent the account_already_linked_to_different_user error, avoid automatically linking a provider to whichever user is currently signed in unless you explicitly confirm ownership with the user.

account_already_linked_to_different_user prevention: clear UI communication

To prevent the account_already_linked_to_different_user error, if you provide a 'Connect account' UI, clearly communicate which user will receive the link and what to do if the provider is already linked elsewhere.

account_already_linked_to_different_user prevention: disable linking for sign-in-only

To prevent the account_already_linked_to_different_user error, consider disabling linking for providers you only want to use for sign-in, to avoid accidental cross-linking.

account_already_linked_to_different_user debugging: inspect account table

To debug the account_already_linked_to_different_user error locally, inspect the account database table. Rows are keyed by providerId (e.g., 'google') and accountId (e.g., OIDC sub), pointing to a userId. Identify which user currently owns the provider link and decide whether to unlink, merge, or keep as-is.

internal_server_error troubleshooting steps

To fix an internal_server_error: check server logs for detailed error information, verify database connectivity and configuration, ensure all required environment variables are set correctly, and review any custom hooks or adapters for runtime errors.

internal_server_error code definition

The internal_server_error error occurs when an unexpected failure happens inside the authentication process.

Complete list of Better Auth error codes

Better Auth generates errors that redirect users to the `/api/auth/error` page. The complete list of error codes includes: invalid_callback_request, invalid_code, internal_server_error, state_not_found, state_invalid, state_mismatch, no_code, no_callback_url, oauth_provider_not_found, email_not_found, email_doesn't_match, unable_to_get_user_info, unable_to_link_account, unable_to_create_user, unable_to_create_session, account_not_linked, account_already_linked_to_different_user, and signup_disabled.

invalid_code error fix: restart authentication flow

To fix the invalid_code error, restart the authentication flow to generate a new code.

invalid_code error fix: code usage constraints

To fix the invalid_code error, ensure the code is used only once and within its valid time window.

invalid_code error fix: verify callback endpoint

To fix the invalid_code error, verify that the correct code is being sent to the callback endpoint.

invalid_code error description

The invalid_code error occurs when the authentication code is invalid, expired, or cannot be verified.

no_callback_url common cause: reverse proxy or middleware altered state

The no_callback_url error can occur if a reverse proxy, CDN, or middleware altered the OAuth flow, causing the app to read a different or empty state.

no_callback_url error definition

The no_callback_url error occurs during the OAuth flow when the request reaches the /api/auth/callback endpoint but the state data does not contain a callback URL. Better Auth stores metadata in state when the flow starts, including where to redirect after a successful sign-in or link. If that URL is missing at callback time, the flow cannot safely continue.

no_callback_url resolution: use Better Auth methods

To resolve the no_callback_url error, always initiate OAuth using Better Auth's built-in methods so that state is generated with the needed fields including the callback URL.

no_callback_url common cause: flow not started via Better Auth

The no_callback_url error can occur if the OAuth flow was not started via Better Auth APIs, meaning the state payload never included a callback URL.

invalid_callback_request resolution: confirm required parameters

To resolve invalid_callback_request, confirm the callback includes required parameters such as code and state for standard OAuth flows.

invalid_callback_request resolution: debug locally

To resolve invalid_callback_request, use DevTools Network tab to inspect the callback request and verify parameters are present and well-formed. Compare dev/staging/prod credentials to ensure there are no environment differences causing different flows or endpoints.

invalid_callback_request edge case: mobile/WebView

Mobile, WebView, or deep-link flows can drop query parameters during handoff, causing invalid_callback_request.

invalid_callback_request edge case: parameter fragments

Some providers can return parameters in fragments, but the server will not receive fragments. Ensure the provider uses query parameters or body for server-side callbacks to avoid invalid_callback_request.

invalid_callback_request edge case: multiple redirects

Multiple redirects including HTTP to HTTPS transitions can lose parameters if not configured correctly, causing invalid_callback_request.

invalid_callback_request automatic handling

Callback parameters are normally handled automatically by Better Auth. If the invalid_callback_request error appears, it often indicates manual access to the /api/auth/callback route, a proxy or redirect that stripped parameters, or an integration mismatch.

invalid_callback_request resolution: preserve query/body through infrastructure

To resolve invalid_callback_request, check that reverse proxies (Vercel, Cloudflare, Nginx) and app rewrites forward the full query string and request body intact. If middleware intercepts the callback, ensure it forwards all parameters without modification.

invalid_callback_request error description

The invalid_callback_request error is thrown during OAuth callback when the incoming request cannot be parsed or is missing required fields.

invalid_callback_request common cause: query/body parameters stripped

The invalid_callback_request error can occur when query or body parameters are stripped by a reverse proxy, CDN, or framework rewrite.

invalid_callback_request common cause: double-encoding

Double-encoding or improper URL encoding of parameters can cause the invalid_callback_request error by making parsing fail.

invalid_callback_request common cause: callback URL mismatch

Callback URL mismatch at the provider can trigger an intermediate redirect that drops parameters, causing the invalid_callback_request error.

invalid_callback_request common cause: middleware routing

Middleware or route grouping that sends the request to a different handler than intended can cause the invalid_callback_request error.

invalid_callback_request common cause: very long URLs

Very long URLs can get truncated by an intermediary (rare but possible with some proxies), causing the invalid_callback_request error.

invalid_callback_request resolution: verify callback method

To resolve invalid_callback_request, ensure your provider is configured to use the method your route expects. For Authorization Code flow, this is commonly GET with query parameters.

no_code error debugging steps

To debug the no_code error locally, inspect the callback request in DevTools Network tab and verify whether code or error parameters are present. Log the raw query/body received by the callback handler during development to see exactly what arrived. Compare dev/staging/prod credentials and redirect URIs to ensure they are consistent across environments.

no_code error definition

The no_code error occurs during the OAuth callback when the authorization code is missing from the request. In the Authorization Code flow, the provider redirects back to the /api/auth/callback route with a code parameter (and typically state). Without the code, Better Auth cannot exchange it for tokens, so the request is rejected.

no_code error common causes

Common causes of the no_code error include: The OAuth flow was not started correctly (wrong response type or custom URL missing required params). The provider returned an error instead of a code (for example, user canceled consent), so only error/error_description are present. Query parameters were stripped by a reverse proxy, CDN, or framework rewrite. Callback URL mismatch at the provider caused an intermediate redirect that dropped query parameters. Mobile/WebView or deep-link handoff opened a new context that lost the query string. Using a response mode the handler does not read (for example, form_post body vs query parameters).

no_code error resolution - standard Authorization Code flow

To resolve the no_code error, start the OAuth flow through Better Auth so the provider receives the correct parameters and the app expects a code. In the provider settings, ensure the app is configured for Authorization Code with PKCE where applicable.

no_code error resolution - verify callback URL

To resolve the no_code error, confirm the provider's configured redirect URI exactly matches the /api/auth/callback route (protocol, host, path). Ensure infrastructure such as proxies, rewrites, and middleware preserves the full query string and does not redirect in ways that drop parameters.

Fix oauth_provider_not_found: use correct callback route shape

Ensure your application exposes a callback route like /api/auth/callback/[provider] (framework-specific syntax). When initiating the OAuth flow, ensure the redirect URI includes the provider segment so the provider returns to /api/auth/callback/<provider>.

oauth_provider_not_found error definition

The oauth_provider_not_found error occurs when Better Auth cannot identify a provider for the callback path, either because the provider segment is missing or because no provider with that id is configured.

OAuth callback route expected format

Better Auth expects the callback route to be shaped like /api/auth/callback/<provider>. If the <provider> segment is absent (for example, a request to /api/auth/callback without the provider), Better Auth cannot determine which integration should handle the callback and rejects the request.

Common cause of oauth_provider_not_found

The error commonly occurs when visiting /api/auth/callback directly without the trailing provider segment.

Fix oauth_provider_not_found: configure infrastructure

Check proxy and CDN rewrites (Vercel, Cloudflare, Nginx) to ensure they do not strip the final path segment. Align trailing slash behavior across environments so that /api/auth/callback/<provider> is preserved.

Fix oauth_provider_not_found: avoid manual access

Do not navigate to /api/auth/callback directly. Always start OAuth via Better Auth APIs which generate the correct provider-specific callback URL.

Debug oauth_provider_not_found locally

To debug this error, inspect the request URL received by your server to confirm the <provider> segment is present. Log router and path parameters in your callback handler to verify the provider value. Compare environment configs (routes, basePath, rewrites) to ensure the same path structure is used everywhere.

oauth_provider_not_found: trailing slash edge case

Trailing slash normalization may alter routing if your framework treats /callback/google/ differently from /callback/google. Configure consistent behavior across your application.

signup_disabled fix using database hooks instead of disableSignUp option

When using the disableSignUp option with stateless mode, the signup_disabled error occurs. The recommended approach is to use database hooks instead to handle signup restrictions. Implement a before hook on user.create that checks if the user is allowed to sign up, and throw an APIError with code BAD_REQUEST and message 'Signup is disabled' if not allowed.

Database hooks signup validation example

Use databaseHooks with a user.create.before hook to validate signups: ```ts import { betterAuth } from "better-auth"; import { APIError } from "better-auth/api"; export const auth = betterAuth({ databaseHooks: { user: { create: { before: async (user, ctx) => { const isAllowedToSignUp = await isAllowedToSignUp(user, ctx); if (!isAllowedToSignUp) { throw new APIError("BAD_REQUEST", { message: "Signup is disabled", }); } }, }, }, } }); ```

signup_disabled error when disableSignUp is true

The signup_disabled error occurs when you disable sign up in your oauth provider config and a user tries to sign up with that provider.

Resolving state_invalid: verify cookie values

To resolve state_invalid errors, use your browser's DevTools (Application, then Cookies) to confirm that the better-auth.oauth_state cookie is set before the redirect and still exists unmodified when the callback arrives.

Cookie state storage example configuration

To use the cookie state storage strategy in Better Auth, configure auth.ts with: export const auth = betterAuth({ account: { storeStateStrategy: 'database' } });

state_invalid error definition

The state_invalid error occurs when using the cookie state storage strategy (account.storeStateStrategy: 'cookie'). It means the OAuth state cookie exists but could not be decrypted or the decrypted content could not be parsed as valid JSON. This error is specific to the cookie strategy; on the default database strategy, state failures surface as other codes such as state_mismatch.

Give your agent this brain