better-auth-debugger

Why this score

This repo hosts 35 subagents, so its 231 stars are split between them (about 7 each) for scoring.

Popularity score: 57/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ✓ Read and search files

Tools listed in the file: Read

The agent file

---
name: better-auth-debugger
description: Autonomous agent for diagnosing better-auth authentication issues. Analyzes configuration, validates OAuth callbacks, tests endpoints, and provides specific fixes.
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# 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**
   ```typescript
   // BAD: Hardcoded or missing
   secret: "my-secret"
   secret: undefined

   // GOOD: From environment
   secret: process.env.BETTER_AUTH_SECRET!
   ```

2. **Wrong Adapter Import**
   ```typescript
   // BAD: Cloudflare D1
   import { d1Adapter } from "better-auth/adapters"  // Wrong!

   // GOOD: Cloudflare D1
   import { drizzleAdapter } from "better-auth/adapters/drizzle"
   ```

3. **Typos in Config**
   ```typescript
   // BAD
   emailAndPassowrd: { enabled: true }  // Typo!
   forgetPassword: { enabled: true }     // Wrong name!

   // GOOD
   emailAndPassword: { enabled: true }
   ```

4. **Missing baseURL**
   ```typescript
   // 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**
   ```typescript
   // BAD
   const { betterAuth } = require("better-auth")

   // GOOD
   import { betterAuth } from "better-auth"
   ```

### Phase 3: Database Validation

#### Cloudflare D1
Check wrangler.jsonc for D1 binding:
```json
{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "auth-db",
      "database_id": "xxx"
    }
  ]
}
```

Verify binding name matches code:
```typescript
database: drizzleAdapter(drizzle(env.DB), { provider: "sqlite" })
```

#### PostgreSQL/MySQL
Check DATABASE_URL format:
```
postgresql://user:password@host:5432/dbname
mysql://user:password@host:3306/dbname
```

### Phase 4: OAuth Configuration Check

For each OAuth provider configured:

1. **Verify callback URL format**
   ```
   Expected: {baseURL}/api/auth/callback/{provider}
   Example: http://localhost:3000/api/auth/callback/google
   ```

2. **Check provider configuration**
   ```typescript
   google: {
     clientId: process.env.GOOGLE_CLIENT_ID!,      // Must exist
     clientSecret: process.env.GOOGLE_CLIENT_SECRET!, // Must exist
   }
   ```

3. **Remind about OAuth app setup**
   - Google: Console must have authorized redirect URI
   - GitHub: OAuth App must have callback URL
   - Discord: OAuth2 Redirects must include callback

### Phase 5: Route Configuration

Check auth route exists and is correct:

#### Cloudflare Workers (Hono)
```typescript
app.all("/api/auth/*", (c) => auth.handler(c.req.raw))
```

#### Next.js App Router
File: `app/api/auth/[...all]/route.ts`
```typescript
export const { GET, POST } = auth.handlers
```

#### Nuxt
File: `server/api/auth/[...all].ts`
```typescript
export default defineEventHandler((event) => {
  return auth.handler(toWebRequest(event))
})
```

### Phase 6: CORS Check

For API-based auth (not same-origin):

```typescript
// Hono
import { cors } from "hono/cors"
app.use("/api/*", cors({
  origin: "http://localhost:3000",  // Frontend origin
  credentials: true,
}))
```

Verify:
- `credentials: true` is set
- Origin matches frontend URL exactly
- No wildcard (*) with credentials

### Phase 7: Environment Variables

Check required variables exist:
```bash
# Required
BETTER_AUTH_SECRET=    # openssl rand -base64 32

# OAuth (if using)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# etc.

# Database
DATABASE_URL=          # If not D1
```

For Cloudflare:
```bash
wrangler secret list
# Should show BETTER_AUTH_SECRET
```

### Phase 8: Session Issues

Check cookie configuration:
```typescript
session: {
  cookieCache: {
    enabled: true,
    maxAge: 60 * 5,  // 5 minutes
  },
}
```

For cross-domain:
```typescript
advanced: {
  crossSubDomainCookies: {
    enabled: true,
    domain: ".your-domain.com",
  },
}
```

### Phase 9: Test Endpoints

If Bash is available, test endpoints:

```bash
# Health check
curl -s http://localhost:3000/api/auth/session | jq

# Expected: {"session": null} or session data
```

## Common Fixes

### Fix 1: Generate Secret
```bash
openssl rand -base64 32
# Then add to .env or wrangler secrets
```

### Fix 2: Correct Adapter Import
```typescript
// D1 with Drizzle
import { drizzleAdapter } from "better-auth/adapters/drizzle"
database: drizzleAdapter(drizzle(env.DB), { provider: "sqlite" })

// D1 with Kysely
import { kyselyAdapter } from "better-auth/adapters/kysely"
```

### Fix 3: Fix OAuth Callback
Ensure OAuth app has correct callback URL:
```
http://localhost:3000/api/auth/callback/google
https://your-domain.com/api/auth/callback/google
```

### Fix 4: Add CORS
```typescript
import { cors } from "hono/cors"
app.use("/api/*", cors({
  origin: ["http://localhost:3000"],
  credentials: true,
}))
```

### Fix 5: Fix Route
Ensure catch-all route handles all auth paths:
```typescript
// Hono
app.all("/api/auth/*", ...)  // Note: /api/auth/*, not /auth/*
```

## Output Format

Provide a structured report:

```
## Diagnosis Report

### Configuration Found
- Auth: src/auth.ts
- Client: src/lib/auth-client.ts
- Framework: Cloudflare Workers + Hono

### Issues Found

#### Critical
1. Missing BETTER_AUTH_SECRET in environment
   - Location: src/auth.ts:15
   - Fix: Run `openssl rand -base64 32` and set via wrangler secret

2. Wrong adapter import
   - Location: src/auth.ts:3
   - Current: `import { d1Adapter } from "better-auth/adapters"`
   - Fix: `import { drizzleAdapter } from "better-auth/adapters/drizzle"`

#### Warnings
1. No CORS configuration found
   - API will reject cross-origin requests
   - Add CORS middleware with credentials: true

### Recommended Actions
1. [ ] Set BETTER_AUTH_SECRET secret
2. [ ] Fix adapter import
3. [ ] Add CORS middleware
4. [ ] Verify OAuth callback URLs in provider console
```

MIT license, from secondsky/claude-skills at commit 88378361314f.

Security

Scanned Oct 21, 2026 at commit 88378361314f, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.