Improve error handling for headers/cookies/draftMode in 'use cache' (#81716)

This ensures that we show a proper error with an error stack
(potentially source-mapped) when accessing
`headers`/`cookies`/`draftMode` in `'use cache'`, even when caught in
user-land code. For `searchParams` (currently triggering a timeout
error) we'll need a slightly different solution, which will be handled
in a future PR.

The approach chosen here is somewhat temporary, as we'd like to
implement compile-time errors instead for accessing any kind of request
data in `'use cache'` functions. However, this would require a larger
change to our bundlers.

closes NAR-201

Author: unstubbable

packages/next/src/server/app-render/app-render.tsx

@@ -135,6 +135,7 @@ import {
   PreludeState,
   consumeDynamicAccess,
   type DynamicAccess,
+  logDisallowedDynamicError,
 } from './dynamic-rendering'
 import {
   getClientComponentLoaderMetrics,
@@ -1456,7 +1457,8 @@ async function renderToHTMLOrFlightImpl(
     // If we encountered any unexpected errors during build we fail the
     // prerendering phase and the build.
     if (workStore.invalidDynamicUsageError) {
-      throw workStore.invalidDynamicUsageError
+      logDisallowedDynamicError(workStore, workStore.invalidDynamicUsageError)
+      throw new StaticGenBailoutError()
     }
     if (response.digestErrorsMap.size) {
       const buildFailingError = response.digestErrorsMap.values().next().value
@@ -3047,7 +3049,8 @@ async function prerenderToStream(
       // We don't need to continue the prerender process if we already
       // detected invalid dynamic usage in the initial prerender phase.
       if (workStore.invalidDynamicUsageError) {
-        throw workStore.invalidDynamicUsageError
+        logDisallowedDynamicError(workStore, workStore.invalidDynamicUsageError)
+        throw new StaticGenBailoutError()
       }
 
       let initialServerResult

packages/next/src/server/app-render/dynamic-rendering.ts

@@ -678,7 +678,10 @@ export enum PreludeState {
   Errored = 2,
 }
 
-function logDisallowedDynamicError(workStore: WorkStore, error: Error): void {
+export function logDisallowedDynamicError(
+  workStore: WorkStore,
+  error: Error
+): void {
   console.error(error)
 
   if (!workStore.dev) {
@@ -700,11 +703,6 @@ export function throwIfDisallowedDynamic(
   dynamicValidation: DynamicValidationState,
   serverDynamic: DynamicTrackingState
 ): void {
-  if (workStore.invalidDynamicUsageError) {
-    logDisallowedDynamicError(workStore, workStore.invalidDynamicUsageError)
-    throw new StaticGenBailoutError()
-  }
-
   if (prelude !== PreludeState.Full) {
     if (dynamicValidation.hasSuspenseAboveBody) {
       // This route has opted into allowing fully dynamic rendering

packages/next/src/server/request/cookies.ts

@@ -81,9 +81,12 @@ export function cookies(): Promise<ReadonlyRequestCookies> {
     if (workUnitStore) {
       switch (workUnitStore.type) {
         case 'cache':
-          throw new Error(
+          const error = new Error(
             `Route ${workStore.route} used "cookies" inside "use cache". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "cookies" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache`
           )
+          Error.captureStackTrace(error, cookies)
+          workStore.invalidDynamicUsageError ??= error
+          throw error
         case 'unstable-cache':
           throw new Error(
             `Route ${workStore.route} used "cookies" inside a function cached with "unstable_cache(...)". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "cookies" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`

packages/next/src/server/request/draft-mode.ts

@@ -229,13 +229,13 @@ class DraftMode {
   public enable() {
     // We have a store we want to track dynamic data access to ensure we
     // don't statically generate routes that manipulate draft mode.
-    trackDynamicDraftMode('draftMode().enable()')
+    trackDynamicDraftMode('draftMode().enable()', this.enable)
     if (this._provider !== null) {
       this._provider.enable()
     }
   }
   public disable() {
-    trackDynamicDraftMode('draftMode().disable()')
+    trackDynamicDraftMode('draftMode().disable()', this.disable)
     if (this._provider !== null) {
       this._provider.disable()
     }
@@ -286,63 +286,69 @@ function createDraftModeAccessError(
   )
 }
 
-function trackDynamicDraftMode(expression: string) {
-  const store = workAsyncStorage.getStore()
+function trackDynamicDraftMode(expression: string, constructorOpt: Function) {
+  const workStore = workAsyncStorage.getStore()
   const workUnitStore = workUnitAsyncStorage.getStore()
-  if (store) {
+
+  if (workStore) {
     // We have a store we want to track dynamic data access to ensure we
     // don't statically generate routes that manipulate draft mode.
     if (workUnitStore?.phase === 'after') {
       throw new Error(
-        `Route ${store.route} used "${expression}" inside \`after\`. The enabled status of draftMode can be read inside \`after\` but you cannot enable or disable draftMode. See more info here: https://nextjs.org/docs/app/api-reference/functions/after`
+        `Route ${workStore.route} used "${expression}" inside \`after\`. The enabled status of draftMode can be read inside \`after\` but you cannot enable or disable draftMode. See more info here: https://nextjs.org/docs/app/api-reference/functions/after`
       )
     }
 
-    if (store.dynamicShouldError) {
+    if (workStore.dynamicShouldError) {
       throw new StaticGenBailoutError(
-        `Route ${store.route} with \`dynamic = "error"\` couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic#dynamic-rendering`
+        `Route ${workStore.route} with \`dynamic = "error"\` couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic#dynamic-rendering`
       )
     }
 
     if (workUnitStore) {
       switch (workUnitStore.type) {
-        case 'cache':
-          throw new Error(
-            `Route ${store.route} used "${expression}" inside "use cache". The enabled status of draftMode can be read in caches but you must not enable or disable draftMode inside a cache. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache`
+        case 'cache': {
+          const error = new Error(
+            `Route ${workStore.route} used "${expression}" inside "use cache". The enabled status of draftMode can be read in caches but you must not enable or disable draftMode inside a cache. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache`
           )
+          Error.captureStackTrace(error, constructorOpt)
+          workStore.invalidDynamicUsageError ??= error
+          throw error
+        }
         case 'unstable-cache':
           throw new Error(
-            `Route ${store.route} used "${expression}" inside a function cached with "unstable_cache(...)". The enabled status of draftMode can be read in caches but you must not enable or disable draftMode inside a cache. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`
+            `Route ${workStore.route} used "${expression}" inside a function cached with "unstable_cache(...)". The enabled status of draftMode can be read in caches but you must not enable or disable draftMode inside a cache. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`
           )
-        case 'prerender':
+        case 'prerender': {
           const error = new Error(
-            `Route ${store.route} used ${expression} without first calling \`await connection()\`. See more info here: https://nextjs.org/docs/messages/next-prerender-sync-headers`
+            `Route ${workStore.route} used ${expression} without first calling \`await connection()\`. See more info here: https://nextjs.org/docs/messages/next-prerender-sync-headers`
           )
           return abortAndThrowOnSynchronousRequestDataAccess(
-            store.route,
+            workStore.route,
             expression,
             error,
             workUnitStore
           )
+        }
         case 'prerender-client':
           const exportName = '`draftMode`'
           throw new InvariantError(
             `${exportName} must not be used within a client component. Next.js should be preventing ${exportName} from being included in client components statically, but did not in this case.`
           )
         case 'prerender-ppr':
           return postponeWithTracking(
-            store.route,
+            workStore.route,
             expression,
             workUnitStore.dynamicTracking
           )
         case 'prerender-legacy':
           workUnitStore.revalidate = 0
 
           const err = new DynamicServerError(
-            `Route ${store.route} couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/messages/dynamic-server-error`
+            `Route ${workStore.route} couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/messages/dynamic-server-error`
           )
-          store.dynamicUsageDescription = expression
-          store.dynamicUsageStack = err.stack
+          workStore.dynamicUsageDescription = expression
+          workStore.dynamicUsageStack = err.stack
 
           throw err
         case 'request':

packages/next/src/server/request/headers.ts

@@ -79,9 +79,12 @@ export function headers(): Promise<ReadonlyHeaders> {
     if (workUnitStore) {
       switch (workUnitStore.type) {
         case 'cache':
-          throw new Error(
+          const error = new Error(
             `Route ${workStore.route} used "headers" inside "use cache". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache`
           )
+          Error.captureStackTrace(error, headers)
+          workStore.invalidDynamicUsageError ??= error
+          throw error
         case 'unstable-cache':
           throw new Error(
             `Route ${workStore.route} used "headers" inside a function cached with "unstable_cache(...)". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "headers" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`