Next.js 16 App Router + Auth.js v5: Session expires but refresh token is still valid — how to silently re-authenticate without redirect?

[3rr0r467]

Question

I'm using Auth.js v5 (beta) with Next.js 16 App Router and a custom OAuth provider (Keycloak). My setup:

• Access token lifetime: 5 minutes
• Refresh token lifetime: 7 days
• Session maxAge: 30 days

The problem: when the access token expires, the session is treated as expired and the user gets redirected to the login page — even though the refresh token is still valid for days.

I've implemented refresh token rotation in the jwt callback:

callbacks: {                                              
  async jwt({ token, account }) {
    if (account) {                                                                                                                                                                                      
      token.accessToken = account.access_token;
      token.refreshToken = account.refresh_token;                                                                                                                                                       
      token.accessTokenExpires = Date.now() + account.expires_in * 1000;
      return token;                                                                                                                                                                                     
    }
                                                                                                                                                                                                        
    // Return token if still valid                                                                                                                                                                      
    if (Date.now() < token.accessTokenExpires) {
      return token;                                                                                                                                                                                     
    }                                                     
                                                                                                                                                                                                        
    // Attempt refresh                                    
    const refreshed = await refreshAccessToken(token);
    return refreshed;                                                                                                                                                                                   
  },
}                                                                                                                                                                                                       
                                                          
async function refreshAccessToken(token) {                                                                                                                                                              
  const res = await fetch(`${KEYCLOAK_URL}/protocol/openid-connect/token`, {
    method: "POST",                                                                                                                                                                                     
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({                                                                                                                                                                         
      grant_type: "refresh_token",                        
      client_id: CLIENT_ID,                                                                                                                                                                             
      client_secret: CLIENT_SECRET,                       
      refresh_token: token.refreshToken,                                                                                                                                                                
    }),                                                                                                                                                                                                 
  });
                                                                                                                                                                                                        
  if (!res.ok) throw new Error("Refresh failed");         
                                                                                                                                                                                                        
  const data = await res.json();                          
  return {
    ...token,
    accessToken: data.access_token,                                                                                                                                                                     
    refreshToken: data.refresh_token ?? token.refreshToken,                                                                                                                                             
    accessTokenExpires: Date.now() + data.expires_in * 1000,                                                                                                                                            
  };                                                                                                                                                                                                    
}                                                         

Issues I'm hitting:

1. Parallel RSC requests cause race conditions — Next.js 16 App Router fires multiple RSC requests on navigation. If the access token expires at that moment, multiple parallel calls to jwt callback
   all try to refresh with the same token. With Keycloak's token rotation, the second request gets a 400 because the first already rotated the refresh token.
2. No built-in way to deduplicate refresh calls — The jwt callback runs per-request with no shared state between parallel invocations. There's no built-in lock or single-flight mechanism.
3. Session appears expired on the client — When refresh fails due to the race condition, useSession() returns unauthenticated and middleware redirects to sign-in, even though the user had a valid
   refresh token moments ago.

What I've tried:

• Setting maxAge to match refresh token lifetime — doesn't help because the jwt callback still races
• refetchInterval on SessionProvider — causes even more parallel refresh attempts
• Wrapping refreshAccessToken in a module-level Promise cache — unclear if this works reliably in Next.js App Router since the jwt callback may run in different execution contexts

Questions:

1. Is there a recommended pattern for single-flight token refresh in Auth.js v5 with App Router?
2. Should I refresh proactively (before expiry) to avoid the race window?
3. Does Auth.js plan to address this internally? (I saw Discussion Various issues with refresh token rotation #3940 has been open since 2022)

How to reproduce (optional)

1. Configure Auth.js v5 with any OAuth provider that rotates refresh tokens
2. Set short access token lifetime (e.g. 5 min)
3. Wait for access token to expire
4. Navigate using — multiple parallel RSC requests trigger simultaneous refresh attempts
5. Second refresh fails → user gets logged out

Expected behavior (optional)

Auth.js should deduplicate concurrent refresh token requests so that only one refresh call is made, and all parallel requests share the result.

Information about Prisma Schema, Client Queries and Environment (optional)

• OS: macOS / Debian (Docker)
• Next.js: 16.1.6
• Auth.js: @auth/nextjs-adapter 5.0.0-beta.25
• Node.js: 22.x
• OAuth Provider: Keycloak 26.x

[sloweyyy]

This is a known pain point with Auth.js v5 + App Router. The core issue is that the jwt callback has no built-in concurrency control, and Next.js 16 fires parallel RSC requests on navigation. Here's how to solve each part:

1. Single-flight token refresh — deduplicate with a shared Promise

The jwt callback runs in the same Node.js process (assuming self-hosted, not Edge), so module-level state works:

// lib/auth-refresh.ts
let inflightRefresh: Promise<any> | null = null;

export async function refreshAccessTokenOnce(token: any) {
  if (inflightRefresh) return inflightRefresh;

  inflightRefresh = refreshAccessToken(token).finally(() => {
    inflightRefresh = null;
  });

  return inflightRefresh;
}

async function refreshAccessToken(token: any) {
  const res = await fetch(`${KEYCLOAK_URL}/protocol/openid-connect/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: token.refreshToken,
    }),
  });

  if (!res.ok) throw new Error("Refresh failed");

  const data = await res.json();
  return {
    ...token,
    accessToken: data.access_token,
    refreshToken: data.refresh_token ?? token.refreshToken,
    accessTokenExpires: Date.now() + data.expires_in * 1000,
  };
}

Then in your auth config:

callbacks: {
  async jwt({ token, account }) {
    if (account) {
      token.accessToken = account.access_token;
      token.refreshToken = account.refresh_token;
      token.accessTokenExpires = Date.now() + account.expires_in * 1000;
      return token;
    }

    if (Date.now() < token.accessTokenExpires) return token;

    try {
      return await refreshAccessTokenOnce(token);
    } catch {
      return { ...token, error: "RefreshTokenError" };
    }
  },
}

All parallel RSC requests share the same in-flight Promise — only one hits Keycloak.

2. Proactive refresh — avoid the race window entirely

Instead of waiting for the token to expire and then racing, refresh it before it expires:

async jwt({ token, account }) {
  if (account) { /* ... initial login ... */ }

  const bufferMs = 60 * 1000; // refresh 60s before expiry
  if (Date.now() < token.accessTokenExpires - bufferMs) {
    return token; // still fresh, no refresh needed
  }

  try {
    return await refreshAccessTokenOnce(token);
  } catch {
    return { ...token, error: "RefreshTokenError" };
  }
}

This way, the refresh happens during normal navigation while the access token is still valid. By the time it actually expires, you already have a new one.

3. Handle refresh failure gracefully on the client

Instead of letting middleware redirect to sign-in immediately, surface the error so the client can retry:

// In your session callback
async session({ session, token }) {
  session.error = token.error;
  return session;
}

// In your client component
"use client";
import { useSession, signIn } from "next-auth/react";

export function AuthGuard({ children }) {
  const { data: session } = useSession();

  if (session?.error === "RefreshTokenError") {
    signIn("keycloak"); // force re-auth only when refresh truly fails
    return null;
  }

  return children;
}

Regarding Discussion #3940 — Auth.js hasn't built in single-flight refresh because the jwt callback is designed to be stateless and edge-compatible. Module-level state only works in Node.js runtime (self-hosted). On edge/serverless, each invocation is isolated, so there's no universal solution they can ship. The proactive refresh approach is the most robust because it sidesteps the concurrency issue entirely.

TL;DR: Combine proactive refresh (60s buffer before expiry) + in-flight Promise deduplication. This eliminates the race condition and keeps users logged in as long as the refresh token is valid.