Next.js Middleware Session Validation#

Better Auth supports multiple middleware strategies for session-based route protection in Next.js, with the correct approach depending on the Next.js version and the trade-off between performance and security.

Core principle: Middleware-level checks should be treated as optimistic redirects only. Always re-validate the session in the server component, server action, or route handler that handles sensitive data or state changes. 1

Approach by Next.js Version#

Next.js 16+ — Proxy Mode#

Next.js 16 replaces middleware.ts with proxy.ts. The function signature changes from middleware → proxy, but all Better Auth methods work identically. 2

The proxy runs on the Node.js runtime, enabling full session validation via auth.api.getSession() with database access — no HTTP round-trip required. 3

Migration: Use the Next.js codemod (npx @next/codemod@canary middleware-to-proxy .) or manually rename the file and function. 4

Next.js 15.2.0+ — Node.js Runtime Middleware#

Next.js 15.2.0 introduced experimental Node.js runtime support for middleware. Set runtime: "nodejs" in the exported config object to unlock auth.api.getSession() with full database access. 5

Note: Node.js runtime in middleware is experimental before Next.js 16. Upgrading to Next.js 16+ is recommended for stable proxy support. 6

Next.js 13–15.1.x — Edge Runtime Middleware#

Edge Runtime cannot make database calls. Two strategies are available:

• getSessionCookie(request) — synchronously reads the session token from request cookies. Checks cookie existence only; does not validate or decode the session. Suitable for optimistic redirects. 7
• getCookieCache(request) — async function that decodes the session from a signed/encrypted cookie cache (supports compact, jwt, jwe encoding strategies). Validates signature and expiry, but no database check. 8
• HTTP fetch to /api/auth/get-session — for 15.1.x and below, the only way to get a full validated session is via an HTTP call back to the auth route, forwarding request cookies. 9

Cookie-Based Check Functions#

Both helpers are exported from better-auth/cookies and located in packages/better-auth/src/cookies/index.ts.

Custom cookie names: If you've configured a custom cookieName or cookiePrefix in auth.ts, pass matching options to getSessionCookie() — it does not automatically read from auth.ts. 10

Server-Side Session Validation (Required for Security)#

Middleware redirects are never sufficient on their own. Validate the session in every protected page or action using auth.api.getSession(): 11

// app/dashboard/page.tsx
const session = await auth.api.getSession({ headers: await headers() });
if (!session) redirect("/sign-in");

In RSCs, the cookie cache is not refreshed because RSCs cannot set cookies — it only updates through client-initiated server actions or route handlers. 12

Session Validation Internals#

The central session resolution function is getSessionFromCtx, which decides between cookie cache and database lookup based on deployment mode (stateful vs. stateless). 13

In stateful deployments (database or secondaryStorage configured), token routes force disableCookieCache: true so that server-side session revocations take immediate effect. 13 This is gated by hasServerSessionStore().

Known issue (v1.6.x): A concurrency race in ensureAsyncStorage can cause intermittent "No request state found" errors and spurious null session returns on cold isolate startup, most commonly on edge runtimes fanning out parallel auth.api.getSession() calls. Workaround: serialize the first call on cold start. Fix tracked in PR #9862. 13

Key References#