Troubleshooting — BolkAuth

Use this page when an integration compiles but auth behavior is not working as expected.

Check these first:

Check	Fix
Auth API is protected by middleware	Add `"/api/auth"` to `publicRoutes`.
Wrong provider base URL	Set `BolkAuthProvider config={{ baseURL: "/api/auth" }}`.
Response is cached	Keep auth responses uncached. The Next.js handler sets `Cache-Control` when missing.
Cross-site cookie restrictions	Keep frontend and auth API on the same site when possible.

Infinite Redirect Loop

The sign-in page is probably protected by middleware. Add auth pages to public routes:

export default bolkAuthMiddleware(auth, {
  publicRoutes: ["/", "/sign-in", "/sign-up", "/api/auth"],
});

OAuth Callback Fails

Verify that your provider callback URL uses the current BolkAuth OAuth route shape:

https://yourapp.com/api/auth/oauth/github/callback
https://yourapp.com/api/auth/oauth/google/callback

Also check that provider credentials are set:

echo "$GITHUB_CLIENT_ID"
echo "$GITHUB_CLIENT_SECRET"

`oauth_error` or State Mismatch

OAuth state is stored in an oauth_state cookie. State mismatches usually mean:

The callback returned to a different origin.
Cookies were blocked or cleared during the redirect.
The callback URL in the provider dashboard is not exact.

`invalid_credentials`

For email/password sign-in:

Make sure the user exists.
Make sure the account has a password value.
Make sure the password was created through BolkAuth or hashed in a compatible format.

OTP Errors

Code	Fix
`otp_not_configured`	Add `email.sendOTP` to `createBolkAuth`.
`invalid_otp`	Ask the user to enter a fresh code. Codes are one-time use and expire.
`invalid_email`	Validate the email before calling `sendCode`.

Missing Database Tables

Run migrations for the adapter you use:

# Drizzle
pnpm drizzle-kit generate
pnpm drizzle-kit migrate
 
# Prisma
npx prisma migrate deploy

TypeScript Cannot Find Package Exports

Check that the package is installed in the app workspace, not only at the monorepo root:

pnpm list @bolkauth/core @bolkauth/react @bolkauth/nextjs

For Drizzle, use supported subpath exports:

import { createDrizzleAdapter } from "@bolkauth/adapter-drizzle/pg";
import { createDrizzleAdapter as createMysqlAdapter } from "@bolkauth/adapter-drizzle/mysql";

Build Fails in Docs App

If the docs app fails because old generated routes are stale, clean and rebuild:

pnpm --filter docs clean
pnpm --filter docs build

On this page