better-auth-debugger

better-auth Debugger Agent

Autonomously diagnose and fix better-auth authentication issues.

Trigger Conditions

Use this agent when user reports:

• Authentication not working
• OAuth redirect issues
• Session problems
• Database connection errors
• CORS issues
• "Unauthorized" responses
• Configuration errors

Diagnostic Process

Phase 1: Locate Configuration

Search for auth configuration files:

Glob patterns:
- **/auth.ts
- **/auth.config.ts
- **/lib/auth.ts
- **/server/auth.ts

Search for client configuration:

Glob patterns:
- **/auth-client.ts
- **/lib/auth-client.ts

Phase 2: Configuration Analysis

Read the auth configuration and check for common issues:

Critical Issues

1. Missing or Invalid Secret

   // BAD: Hardcoded or missing
   secret: "my-secret"
   secret: undefined
   
   // GOOD: From environment
   secret: process.env.BETTER_AUTH_SECRET!
   

2. Wrong Adapter Import

   // BAD: Cloudflare D1
   import { d1Adapter } from "better-auth/adapters"  // Wrong!
   
   // GOOD: Cloudflare D1
   import { drizzleAdapter } from "better-auth/adapters/drizzle"
   

3. Typos in Config

   // BAD
   emailAndPassowrd: { enabled: true }  // Typo!
   forgetPassword: { enabled: true }     // Wrong name!
   
   // GOOD
   emailAndPassword: { enabled: true }
   

4. Missing baseURL

   // BAD: Not set or wrong
   baseURL: "localhost:3000"  // Missing protocol
   
   // GOOD
   baseURL: process.env.APP_URL  // e.g., "http://localhost:3000"
   

5. CommonJS in ESM Project

   // BAD
   const { betterAuth } = require("better-auth")
   
   // GOOD
   import { betterAuth } from "better-auth"
   

Phase 3: Database Validation

Cloudflare D1

Check wrangler.jsonc for D1 binding:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "auth-db",
      "database_id": "xxx"
    }
  ]
}

Verify binding name matches code:

database: drizzleAdapter(drizzle(env.DB), { provider: "sqlite" })