Troubleshooting

Debugging

Enable verbose logging:

DEBUG=better-auth*

Check browser DevTools Network tab for /api/auth/* requests.

Frequently Asked Questions

Can I use this without a database?

Yes, using database-less mode. Sessions are stored in encrypted cookies. This mode limits some features like session revocation.

Does this work with Nuxt 2?

No. This module requires Nuxt 3.10 or later.

What's the difference from nuxt-auth-utils?

Nuxt Better Auth uses the Better Auth library, which provides:

• More authentication methods (OAuth, magic links, passkeys)
• Plugin ecosystem for features like 2FA, organizations
• TypeScript-first design with full type inference

See the migration guide for detailed comparison.

Can I use a different database?

Yes. Better Auth supports any database with a Drizzle, Prisma, or Kysely adapter. See Better Auth database documentation.

How do I add custom fields to the user?

Configure in Better Auth, then augment types:

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth({
  user: {
    additionalFields: {
      role: { type: 'string', defaultValue: 'user' }
    }
  }
})

How do I enable email verification?

Use Better Auth's email plugin:

How do I implement password reset?

Common Errors

NuxtHub version requirement

If using NuxtHub for database features, you need @nuxthub/core version 0.10.0 or higher. NuxtHub is optional - see NuxtHub Integration for details.

pnpm add @nuxthub/core@latest

"Missing server/auth.config.ts"

The module validates config files at build time. Create server/auth.config.ts exporting defineServerAuth(...).

"Missing app/auth.config.ts"

The module expects a client config file at app/auth.config.ts exporting createAppAuthClient via defineClientAuth().

"auth.config.ts validation failed"

• Ensure the file exports createServerAuth via defineServerAuth().
• Do not set secret/baseURL manually (the module injects these).
• Confirm the file is at the expected path (default: server/auth.config.ts).

No schema file is generated

Schema generation requires NuxtHub. Ensure NuxtHub is installed and DB is configured:

hub: { db: { dialect: 'sqlite' } }

Restart dev server after changing Better Auth plugins.

routeRules changes don't apply

routeRules are synced to page meta during pages:extend. Restart dev server after updating route rules.

API routes aren't protected

Only routeRules.auth is enforced for /api/**. Use routeRules.auth (or call requireUserSession(event) inside handlers) to enforce access.