Better Auth

Common errors

• Column 'verified' does not exist on table 'twoFactor'

  cause The required `verified` column for the `twoFactor` table, introduced in v1.6.2, is missing from your database schema.
  fix Run `npx auth@latest generate` to update your ORM client, then apply the schema migration using your ORM's command (e.g., `npx prisma migrate dev` or `npx drizzle-kit push`).

• AuthError: AUTH_SECRET is not defined

  cause The `AUTH_SECRET` environment variable is not set, which is critical for encrypting and signing session tokens, making the application insecure.
  fix Define the `AUTH_SECRET` environment variable in your application's environment (e.g., `.env` file) with a long, randomly generated string. Do not hardcode secrets in your codebase.

• TypeError: auth.getSession is not a function

  cause This error can occur if the `auth` instance is not correctly initialized or if `getSession` is called without the expected request context (e.g., `req`).
  fix Ensure `auth` is properly instantiated and exported. When calling `getSession` server-side, pass the relevant request object, e.g., `await auth.getSession({ req })`.

• AuthError: Invalid OTP method specified.

  cause The `enableTwoFactor` function was called without a valid `method` parameter or with an unsupported method, following the breaking change in `v1.7.0-beta.0`.
  fix Update your `enableTwoFactor` calls to explicitly specify the `method` as either `'otp'` or `'totp'`, e.g., `auth.enableTwoFactor({ method: 'totp' })`.

Warnings

• breaking The `enableTwoFactor` function now requires a `method` parameter (`'otp' | 'totp'`) and returns a discriminated response object with a `method` field. If `method: 'otp'` is used, `otpOptions.sendOTP` must be configured on the server.
  Fix: Update calls to `enableTwoFactor` to provide the `method` parameter and handle the new discriminated return type. Ensure `otpOptions.sendOTP` is configured for OTP method.
• breaking The `twoFactor` database table now requires a `verified` column. Failing to add this column will prevent TOTP enrollment from working correctly and may lead to schema migration errors.
  Fix: Add a `verified` column to your `twoFactor` database table. Regenerate and apply your ORM migration (e.g., `npx prisma migrate dev` for Prisma or `npx drizzle-kit push` for Drizzle) and then `npx auth@latest generate`.
• breaking The `session.freshAge` calculation now aligns with the session's `createdAt` timestamp instead of `updatedAt`. This change impacts how fresh sessions are determined, potentially affecting session validity logic.
  Fix: Review any custom logic relying on `session.freshAge`. If you need to disable the fresh session check entirely, set `session: { freshAge: 0 }` in your Auth configuration.
• gotcha 2FA enforcement scope was temporarily reverted in `v1.6.4` to apply only to credential sign-in paths. This meant magic link, email OTP, OAuth, SSO, and passkey flows would bypass 2FA challenges in that version.
  Fix: This issue was fixed in `v1.7.0-beta.1` and later to apply 2FA across all sign-in paths. Upgrade to the latest stable version or a `v1.7.0-beta.x` release if comprehensive 2FA enforcement is required.

Install

• npm install better-auth npm
• yarn add better-auth yarn
• pnpm add better-auth pnpm

Imports

• Auth
  wrong:

  const Auth = require('better-auth');

  correct:

  import { Auth } from 'better-auth';

  Better Auth is designed for modern JavaScript environments and TypeScript, primarily using ESM imports.

Quickstart

This quickstart demonstrates how to initialize Better Auth in a TypeScript project using the Prisma adapter. It sets up the core `Auth` instance with a placeholder secret and hints at basic session retrieval in a server-side context.

import { Auth } from 'better-auth';
import { PrismaAdapter } from '@better-auth/adapter-prisma';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export const auth = new Auth({
  adapter: PrismaAdapter(prisma),
  secret: process.env.AUTH_SECRET ?? 'super-secret-dev-key', // IMPORTANT: Use a strong, unique secret in production
  providers: [], // Configure your authentication providers here
});

// Example usage (e.g., in a Next.js API route):
// import { auth } from './auth'; // Adjust path as needed
// import type { NextApiRequest, NextApiResponse } from 'next';
//
// export default async function handler(req: NextApiRequest, res: NextApiResponse) {
//   const session = await auth.getSession({ req });
//   if (!session) {
//     return res.status(401).json({ message: 'Unauthorized' });
//   }
//   res.status(200).json({ user: session.user });
// }