Explain Error

Better Auth Error Diagnostician & Explainer

This skill diagnoses and provides actionable resolutions for common Better Auth runtime errors, client error codes, configuration pitfalls, and database adapter issues.

Common Error Codes & Resolutions

1. INVALID_EMAIL_OR_PASSWORD

• Cause: User credentials do not match database records, or password hashing mismatch.
• Resolution:
  • Verify that password hashing algorithm has not changed between migrations.
  • Verify that input email is trimmed/lowercased if emailAndPassword.autoSignIn or normalization is enabled.
  • Check client-side error handling:

    const { data, error } = await authClient.signIn.email({
      email,
      password,
    })
    if (error?.status === 401 || error?.code === 'INVALID_EMAIL_OR_PASSWORD') {
      // Prompt user with user-friendly message
    }
    

2. USER_ALREADY_EXISTS

• Cause: Attempting to sign up with an email or account ID already in use.
• Resolution:
  • Direct user to sign in or password reset flow.
  • If social login is used with existing email, check accountLinking.enabled:

    export const auth = betterAuth({
      account: {
        accountLinking: {
          enabled: true,
          trustedProviders: ['google', 'github'],
        },
      },
    })
    

3. SESSION_EXPIRED / UNAUTHORIZED

• Cause: Cookie expired, missing credentials: "include" on cross-origin fetch, or cookie domain mismatch.
• Resolution:
  • Client side: ensure authClient has the exact baseURL matching server.
  • Cross-domain setup:

    export const auth = betterAuth({
      trustedOrigins: ['https://app.example.com', 'http://localhost:3000'],
      advanced: {
        crossSubDomainCookies: {
          enabled: true,
          domain: '.example.com',
        },
      },
    })
    

4. FAILED_TO_VERIFY_EMAIL / INVALID_TOKEN

• Cause: Verification token expired or used already.
• Resolution:
  • Verify email verification URL configuration in emailVerification:

    emailVerification: {
      sendOnSignUp: true,
      autoSignInAfterVerification: true,
      sendVerificationEmail: async ({ user, url, token }) => {
        await sendEmail({ to: user.email, url })
      },
    }
    

5. ADAPTER_ERROR / Database Schema Mismatches

• Cause: Database tables do not match Better Auth expectations (missing columns like emailVerified, image, twoFactorEnabled, or relation tables).
• Resolution:
  • Run the Better Auth CLI schema generator / migration tool:

    npx @better-auth/cli generate
    npx @better-auth/cli migrate
    

  • If using Prisma, ensure schema has all required Better Auth models: User, Session, Account, Verification.

6. CORS / Preflight Failure on /api/auth/*

• Cause: Missing CORS headers or allowed methods on the API route handler.
• Resolution:
  • In Next.js / Hono / Express, ensure toNextJsHandler or framework adapter exposes GET and POST.
  • Ensure BETTER_AUTH_URL matches the canonical deployment URL.

Diagnostic Checklist

When debugging an unknown Better Auth issue:

1. Check server console logs with logger: { level: "debug" } enabled in betterAuth().
2. Inspect network tab response payload for the { code, message } JSON object.
3. Verify database adapter connection string and table prefixes.
4. Verify cookie configuration in production (secure: true requires HTTPS).