fix(nextjs): prevent double-wrapping of use cache errors

- Add ClerkUseCacheError class with symbol marker to identify already-formatted errors
- Update auth() and currentUser() to check for ClerkUseCacheError before wrapping
- Tighten isNextjsUseCacheError() regex to reduce false positives
- Update clerkClient.ts to use isClerkUseCacheError

Author: jacekradko

packages/nextjs/src/app-router/server/__tests__/utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { isNextjsUseCacheError, isPrerenderingBailout } from '../utils';
+import { ClerkUseCacheError, isClerkUseCacheError, isNextjsUseCacheError, isPrerenderingBailout } from '../utils';
 
 describe('isPrerenderingBailout', () => {
   it('returns false for non-Error values', () => {
@@ -43,6 +43,40 @@ describe('isPrerenderingBailout', () => {
   });
 });
 
+describe('ClerkUseCacheError', () => {
+  it('is recognized by isClerkUseCacheError', () => {
+    const error = new ClerkUseCacheError('Test message');
+    expect(isClerkUseCacheError(error)).toBe(true);
+  });
+
+  it('preserves original error', () => {
+    const original = new Error('Original');
+    const error = new ClerkUseCacheError('Wrapped', original);
+    expect(error.originalError).toBe(original);
+  });
+
+  it('has correct name', () => {
+    const error = new ClerkUseCacheError('Test');
+    expect(error.name).toBe('ClerkUseCacheError');
+  });
+});
+
+describe('isClerkUseCacheError', () => {
+  it('returns false for regular errors', () => {
+    expect(isClerkUseCacheError(new Error('test'))).toBe(false);
+  });
+
+  it('returns false for non-Error values', () => {
+    expect(isClerkUseCacheError(null)).toBe(false);
+    expect(isClerkUseCacheError('string')).toBe(false);
+    expect(isClerkUseCacheError({})).toBe(false);
+  });
+
+  it('returns true for ClerkUseCacheError', () => {
+    expect(isClerkUseCacheError(new ClerkUseCacheError('test'))).toBe(true);
+  });
+});
+
 describe('isNextjsUseCacheError', () => {
   it('returns false for non-Error values', () => {
     expect(isNextjsUseCacheError(null)).toBe(false);
@@ -65,9 +99,10 @@ describe('isNextjsUseCacheError', () => {
     expect(isNextjsUseCacheError(error)).toBe(true);
   });
 
-  it('returns true for dynamic data source cache errors', () => {
+  it('returns false for generic "cache" mentions without specific patterns', () => {
+    // This should NOT match to reduce false positives - requires "cache scope" not just "cache"
     const error = new Error('Dynamic data source accessed in cache context');
-    expect(isNextjsUseCacheError(error)).toBe(true);
+    expect(isNextjsUseCacheError(error)).toBe(false);
   });
 
   it('returns false for regular prerendering bailout errors', () => {

packages/nextjs/src/app-router/server/auth.ts

@@ -11,7 +11,13 @@ import { unauthorized } from '../../server/nextErrors';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
-import { buildRequestLike, isNextjsUseCacheError, USE_CACHE_ERROR_MESSAGE } from './utils';
+import {
+  buildRequestLike,
+  ClerkUseCacheError,
+  isClerkUseCacheError,
+  isNextjsUseCacheError,
+  USE_CACHE_ERROR_MESSAGE,
+} from './utils';
 
 /**
  * `Auth` object of the currently active user and the `redirectToSignIn()` method.
@@ -136,9 +142,11 @@ export const auth: AuthFn = (async (options?: AuthOptions) => {
 
     return authObject;
   } catch (e: any) {
-    // Catch "use cache" errors that bubble up from Next.js cache boundary
+    if (isClerkUseCacheError(e)) {
+      throw e;
+    }
     if (isNextjsUseCacheError(e)) {
-      throw new Error(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`);
+      throw new ClerkUseCacheError(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`, e);
     }
     throw e;
   }

packages/nextjs/src/app-router/server/currentUser.ts

@@ -3,7 +3,12 @@ import type { PendingSessionOptions } from '@clerk/shared/types';
 
 import { clerkClient } from '../../server/clerkClient';
 import { auth } from './auth';
-import { isNextjsUseCacheError, USE_CACHE_ERROR_MESSAGE } from './utils';
+import {
+  ClerkUseCacheError,
+  isClerkUseCacheError,
+  isNextjsUseCacheError,
+  USE_CACHE_ERROR_MESSAGE,
+} from './utils';
 
 type CurrentUserOptions = PendingSessionOptions;
 
@@ -40,9 +45,11 @@ export async function currentUser(opts?: CurrentUserOptions): Promise<User | nul
 
     return (await clerkClient()).users.getUser(userId);
   } catch (e: any) {
-    // Catch "use cache" errors that bubble up from Next.js cache boundary
+    if (isClerkUseCacheError(e)) {
+      throw e;
+    }
     if (isNextjsUseCacheError(e)) {
-      throw new Error(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`);
+      throw new ClerkUseCacheError(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`, e);
     }
     throw e;
   }

packages/nextjs/src/app-router/server/utils.ts

@@ -1,11 +1,29 @@
 import { NextRequest } from 'next/server';
 
-// Pre-compiled regex patterns for error detection
-const USE_CACHE_PATTERN = /use cache|cache scope/i;
-const DYNAMIC_CACHE_PATTERN = /dynamic data source/i;
-// note: new error message syntax introduced in next@14.1.1-canary.21
-// but we still want to support older versions.
-// https://github.com/vercel/next.js/pull/61332 (dynamic-rendering.ts:153)
+const CLERK_USE_CACHE_MARKER = Symbol.for('clerk_use_cache_error');
+
+/**
+ * Custom error class for "use cache" errors with a symbol marker to prevent double-wrapping.
+ */
+export class ClerkUseCacheError extends Error {
+  readonly [CLERK_USE_CACHE_MARKER] = true;
+
+  constructor(message: string, public readonly originalError?: Error) {
+    super(message);
+    this.name = 'ClerkUseCacheError';
+  }
+}
+
+export const isClerkUseCacheError = (e: unknown): e is ClerkUseCacheError => {
+  return e instanceof Error && CLERK_USE_CACHE_MARKER in e;
+};
+
+// Patterns for Next.js "use cache" errors - tightened to reduce false positives
+const USE_CACHE_WITH_DYNAMIC_API_PATTERN =
+  /inside\s+"use cache"|"use cache".*(?:headers|cookies)|(?:headers|cookies).*"use cache"/i;
+const CACHE_SCOPE_PATTERN = /cache scope/i;
+const DYNAMIC_DATA_SOURCE_PATTERN = /dynamic data source/i;
+// https://github.com/vercel/next.js/pull/61332
 const ROUTE_BAILOUT_PATTERN = /Route .*? needs to bail out of prerendering at this point because it used .*?./;
 
 export const isPrerenderingBailout = (e: unknown) => {
@@ -14,24 +32,18 @@ export const isPrerenderingBailout = (e: unknown) => {
   }
 
   const { message } = e;
-
   const lowerCaseInput = message.toLowerCase();
-  const dynamicServerUsage = lowerCaseInput.includes('dynamic server usage');
-  const bailOutPrerendering = lowerCaseInput.includes('this page needs to bail out of prerendering');
-
-  // Next.js 16+ with cacheComponents: headers() rejects during prerendering
-  // Error: "During prerendering, `headers()` rejects when the prerender is complete"
-  const headersRejectsDuringPrerendering = lowerCaseInput.includes('during prerendering');
 
   return (
-    ROUTE_BAILOUT_PATTERN.test(message) || dynamicServerUsage || bailOutPrerendering || headersRejectsDuringPrerendering
+    ROUTE_BAILOUT_PATTERN.test(message) ||
+    lowerCaseInput.includes('dynamic server usage') ||
+    lowerCaseInput.includes('this page needs to bail out of prerendering') ||
+    lowerCaseInput.includes('during prerendering')
   );
 };
 
 /**
- * Detects if the error is from using dynamic APIs inside a "use cache" component.
- * Next.js 16+ throws specific errors when headers(), cookies(), or other dynamic
- * APIs are accessed inside a cache scope.
+ * Detects Next.js errors from using dynamic APIs (headers/cookies) inside "use cache".
  */
 export const isNextjsUseCacheError = (e: unknown): boolean => {
   if (!(e instanceof Error)) {
@@ -40,19 +52,19 @@ export const isNextjsUseCacheError = (e: unknown): boolean => {
 
   const { message } = e;
 
-  // Check for "use cache" or "cache scope" mentions
-  if (USE_CACHE_PATTERN.test(message)) {
+  // "use cache" with dynamic API context (e.g., 'used `headers()` inside "use cache"')
+  if (USE_CACHE_WITH_DYNAMIC_API_PATTERN.test(message)) {
+    return true;
+  }
+
+  // "cache scope" with dynamic data source (e.g., 'Dynamic data sources inside a cache scope')
+  if (CACHE_SCOPE_PATTERN.test(message) && DYNAMIC_DATA_SOURCE_PATTERN.test(message)) {
     return true;
   }
 
-  // Check compound pattern: requires both "dynamic data source" AND "cache"
-  return DYNAMIC_CACHE_PATTERN.test(message) && message.toLowerCase().includes('cache');
+  return false;
 };
 
-/**
- * Error message for when auth()/currentUser() is called inside a "use cache" function.
- * Exported so it can be reused in auth.ts and currentUser.ts for consistent messaging.
- */
 export const USE_CACHE_ERROR_MESSAGE =
   `Clerk: auth() and currentUser() cannot be called inside a "use cache" function. ` +
   `These functions access \`headers()\` internally, which is a dynamic API not allowed in cached contexts.\n\n` +
@@ -71,21 +83,18 @@ export const USE_CACHE_ERROR_MESSAGE =
 
 export async function buildRequestLike(): Promise<NextRequest> {
   try {
-    // Dynamically import next/headers, otherwise Next12 apps will break
-    // @ts-expect-error: Cannot find module 'next/headers' or its corresponding type declarations.ts(2307)
+    // @ts-expect-error - Dynamically import to avoid breaking Next 12 apps
     const { headers } = await import('next/headers');
     const resolvedHeaders = await headers();
     return new NextRequest('https://placeholder.com', { headers: resolvedHeaders });
   } catch (e: any) {
-    // rethrow the error when react throws a prerendering bailout
     // https://nextjs.org/docs/messages/ppr-caught-error
     if (e && isPrerenderingBailout(e)) {
       throw e;
     }
 
-    // Provide a helpful error message for "use cache" components
     if (e && isNextjsUseCacheError(e)) {
-      throw new Error(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`);
+      throw new ClerkUseCacheError(`${USE_CACHE_ERROR_MESSAGE}\n\nOriginal error: ${e.message}`, e);
     }
 
     throw new Error(

packages/nextjs/src/server/clerkClient.ts

@@ -1,6 +1,6 @@
 import { constants } from '@clerk/backend/internal';
 
-import { buildRequestLike, isNextjsUseCacheError, isPrerenderingBailout } from '../app-router/server/utils';
+import { buildRequestLike, isClerkUseCacheError, isPrerenderingBailout } from '../app-router/server/utils';
 import { createClerkClientWithOptions } from './createClerkClient';
 import { getHeader } from './headers-utils';
 import { clerkMiddlewareRequestDataStorage } from './middleware-storage';
@@ -21,8 +21,7 @@ const clerkClient = async () => {
     if (err && isPrerenderingBailout(err)) {
       throw err;
     }
-    // Re-throw "use cache" errors with the helpful message from buildRequestLike
-    if (err && isNextjsUseCacheError(err)) {
+    if (err && isClerkUseCacheError(err)) {
       throw err;
     }
   }