errors

19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

account_not_linked resolution: review configuration

To resolve account_not_linked errors, ensure environment configs are consistent across deployments.

account_not_linked error definition

The account_not_linked error occurs during an OAuth flow when a provider account is not linked to the current or matched user and, under the current configuration, cannot be linked automatically. This can happen because the provider is untrusted, account linking is disabled, or implicit linking is turned off, even if a matching user exists.

account_not_linked common causes

The account_not_linked error has four common causes: the user previously signed up using a different provider or method; account linking is not enabled or configured; the provider email does not match any existing user; or linking rules such as trusted providers prevent automatic linking.

account_not_linked resolution: enable account linking

To resolve account_not_linked errors, ensure account linking is enabled in your auth configuration. Add providers to account.accountLinking.trustedProviders if required.

account_not_linked resolution: verify user identity matching

To resolve account_not_linked errors, ensure the provider returns a verified email that matches an existing user. Ensure the matching existing user has emailVerified: true, especially if the user row was inserted manually.

account_not_linked resolution: prompt user action

To resolve account_not_linked errors, ask users to sign in using the originally linked provider or method.

email_doesn't_match common causes

The email_doesn't_match error can occur when: the user is logged into the provider with a different email than their app account (e.g., work vs personal); the provider returns an unverified or secondary email that differs from the app account email; email normalization differences such as case sensitivity or dots/aliases on Gmail cause a mismatch; or the user's email changed in the app or at the provider since the original account was created.

email_doesn't_match error definition

The email_doesn't_match error appears during OAuth account linking when a signed-in user tries to link an OAuth provider account but the email returned by the provider does not match the email on the currently authenticated user. Better Auth blocks the link to prevent accidental cross-account linking or account takeover. This error does not occur during normal OAuth sign-in; it is specific to the linking flow.

email_doesn't_match resolution steps

To resolve the email_doesn't_match error, ask the user to align identities by having them switch to the correct provider account that uses the same email as their app account, or alternatively update the app account email to the intended email if the product allows it and retry linking. To debug locally, log the current user's email in the app and the email returned by the provider profile, inspect whether the provider email is verified or primary and whether any normalization is applied, and confirm which provider credentials (dev/staging/prod) are in use and that the returned identity is the expected one.

email_not_found common causes

The email_not_found error has several common causes: missing or insufficient scopes in the provider configuration (e.g., not requesting email); the user's email is private or not exposed by default (e.g., GitHub private email); the provider returns email only via a separate endpoint and the scope/API call to fetch it was not enabled (e.g., GitHub user:email); provider project or tenant misconfiguration (consent screen, admin consent, restricted claims/attributes); or using different credentials between environments that do not request the same scopes.

email_not_found error definition

The email_not_found error occurs during the OAuth flow when the provider does not return an email address for the user. Better Auth uses the email from the provider to identify or create a user account. If the provider omits the email or returns it as empty/undefined, the request is rejected. This error is only possible through OAuth providers and will not occur in non-OAuth flows.

email_not_found resolution steps

To resolve the email_not_found error: ensure your provider configuration requests the email-related scopes; in the provider's dashboard, confirm the app has permission to request email and the consent screen allows it; inspect the outgoing authorize request to confirm the scopes include 'email' where required; inspect the callback payload (query, id_token claims, userinfo response) to see if an email claim exists; log the provider profile object received by your callback handler to verify whether email is present; and check which environment's provider credentials are in use and whether scopes differ across environments.

Better Auth must be in dependencies not devDependencies

Better Auth and related packages must be installed in dependencies, not devDependencies.

Next.js bundler resolution for dual module hazard

For Next.js users experiencing dual module hazard issues, add better-auth to serverExternalPackages in next.config.js to ensure the bundler resolves the module to the same instance.

Dual module hazard error symptoms and causes

The error 'No request state found. Please make sure you are calling this function within a runWithRequestState callback' is caused by a dual module hazard where multiple versions of better-auth or @better-auth/core exist in the dependency tree. This commonly occurs after upgrading to v1.4+, particularly in Cloudflare Workers, Nuxt, or when using plugins like oauthProvider.

Diagnosing dual module hazard with package managers

To diagnose a dual module hazard, use: 'pnpm why @better-auth/core' and 'pnpm why better-auth' for pnpm users; 'npm ls @better-auth/core' and 'npm ls better-auth' for npm users; 'yarn why @better-auth/core' and 'yarn why better-auth' for yarn users. Multiple versions listed indicates a dual module hazard.

Fixing dual module hazard with clean reinstall

To fix a dual module hazard: remove node_modules and lockfile (pnpm-lock.yaml, package-lock.json, or yarn.lock), then reinstall dependencies with pnpm install, npm install, or yarn install. Check package.json to ensure all Better Auth related packages (better-auth, @better-auth/core, @better-auth/oauth-provider, etc.) use compatible versions.

Dual module hazard fix for Yarn v1 and pnpm v9

For Yarn v1 (Classic) or pnpm v9, manually install better-call and add it to both dependencies and resolutions in package.json to force it to resolve to a single instance. Example: set both 'dependencies' and 'resolutions' to include 'better-call': '^1.1.8'. Note: Yarn v3 and pnpm v10 do not typically have this issue.

Cloudflare Workers compatibility flag for dual module hazard

For Cloudflare Workers users, ensure the nodejs_compat compatibility flag is enabled in wrangler.toml to prevent dual module hazard issues.

Give your agent this brain