Show inner "use cache" as cause of nested-dynamic cache error

When a `"use cache"` propagated a dynamic cache life (`revalidate: 0` or
`expire` under 5 minutes) to a parent without an explicit `cacheLife`,
the resulting error pointed only at the outer cache invocation. With the
inner cache's call site missing, tracing which nested cache was
responsible meant reading through the outer's body — fine when it's
local code, much harder when the dynamism comes from a nested cache
buried in a third-party dependency.

This change attaches the inner invocation as `cause` of the error, so
the dev redbox and the build log show two stacks: the outer that threw,
and the inner that propagated the dynamic life.

The inner call site has to be captured eagerly while `cache()` is still
on the synchronous stack, because we only learn whether the inner
resolved dynamic asynchronously — after `collectResult` finishes and
`propagateCacheEntryMetadata` runs — and by then the inner's frames are
no longer on the JS stack. We only construct the eager `Error` when the
parent is itself a public `"use cache"` (the only case where this entry
could become a propagated origin), so top-level caches skip the
allocation. The eager `Error` is held on
`cacheContext.dynamicNestedCacheError`; once propagation knows the inner
resolved dynamic, it's copied onto the outer store's same-named field,
then carried through the outer's own `collectResult` into its RDC entry
— which the throw site finally reads back as `cause`. We keep the first
dynamic child — the immediate origin from the throwing cache's
perspective.

The two nested-dynamic cache error messages also get a small cleanup:
each used to write `"use cache"` two different ways within the same
sentence (bare and backticked); both now write it the same way.

Author: unstubbable

packages/next/errors.json

@@ -1190,5 +1190,8 @@
   "1189": "Route \"%s\" accessed header \"%s\" which is not defined in the \\`unstable_samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`headers\\` array, or \\`[\"%s\", null]\\` if it should be absent.",
   "1190": "Route \"%s\" accessed param \"%s\" which is not defined in the \\`unstable_samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`params\\` object.",
   "1191": "Route \"%s\" called %s but param%s %s %s not defined in the \\`unstable_samples\\` of \\`unstable_instant\\`. %s requires all route params to be provided.",
-  "1192": "Route \"%s\" accessed root param \"%s\" which is not defined in the \\`unstable_samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`params\\` object."
+  "1192": "Route \"%s\" accessed root param \"%s\" which is not defined in the \\`unstable_samples\\` of \\`unstable_instant\\`. Add it to the sample's \\`params\\` object.",
+  "1193": "This \"use cache\" has a dynamic cache life that was propagated to its parent.",
+  "1194": "A \"use cache\" with short \\`expire\\` (under 5 minutes) is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with longer \\`expire\\`) or remain dynamic (with short \\`expire\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife",
+  "1195": "A \"use cache\" with zero \\`revalidate\\` is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with non-zero \\`revalidate\\`) or remain dynamic (with zero \\`revalidate\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife"
 }

packages/next/src/server/app-render/postponed-state.test.ts

@@ -45,6 +45,7 @@ describe('getDynamicHTMLPostponedState', () => {
         hasExplicitRevalidate: true,
         hasExplicitExpire: true,
         readRootParamNames: undefined,
+        dynamicNestedCacheError: undefined,
       })
     )
 

packages/next/src/server/app-render/work-unit-async-storage.external.ts

@@ -364,6 +364,13 @@ export interface PublicUseCacheStore extends CommonUseCacheStore {
    * Tracks which root param names were read during this cache invocation.
    */
   readonly readRootParamNames: Set<string>
+  /**
+   * The first nested public `'use cache'` invocation with a dynamic cache life
+   * (`revalidate === 0` or `expire < DYNAMIC_EXPIRE`) that propagated up to
+   * this store. Used as `cause` for the nested-dynamic cache error so the
+   * redbox can point at the inner invocation site, not just the outer one.
+   */
+  dynamicNestedCacheError: Error | undefined
 }
 
 export interface PrivateUseCacheStore extends CommonUseCacheStore {

packages/next/src/server/resume-data-cache/cache-store.ts

@@ -92,6 +92,11 @@ export function parseUseCacheCacheStore(
         readRootParamNames: readRootParamNames
           ? new Set(readRootParamNames)
           : undefined,
+        // Serialized RDC entries are non-dynamic by construction (the
+        // serializer drops dynamic entries), so this is never produced from the
+        // wire — the throw path that consumes it is only reachable for dynamic
+        // entries, which only exist in the in-memory RDC.
+        dynamicNestedCacheError: undefined,
       })
     )
   }

packages/next/src/server/resume-data-cache/resume-data-cache.test.ts

@@ -26,6 +26,7 @@ function createMockedCache() {
       hasExplicitRevalidate: true,
       hasExplicitExpire: true,
       readRootParamNames: undefined,
+      dynamicNestedCacheError: undefined,
     })
   )
 
@@ -44,6 +45,7 @@ function createMockedCache() {
       hasExplicitRevalidate: true,
       hasExplicitExpire: true,
       readRootParamNames: undefined,
+      dynamicNestedCacheError: undefined,
     })
   )
 
@@ -62,6 +64,7 @@ function createMockedCache() {
       hasExplicitRevalidate: true,
       hasExplicitExpire: true,
       readRootParamNames: undefined,
+      dynamicNestedCacheError: undefined,
     })
   )
 

packages/next/src/server/use-cache/use-cache-errors.ts

@@ -13,3 +13,18 @@ export class UseCacheDeadlockError extends Error {
     )
   }
 }
+
+/**
+ * Used purely as `cause` for the nested-dynamic cache error: its captured stack
+ * points at the inner `"use cache"` invocation that propagated a dynamic cache
+ * life up to the outer cache. Constructed eagerly in `cache()` while the caller
+ * is still on the synchronous stack — see use-cache-wrapper.ts.
+ */
+export class NestedDynamicUseCacheError extends Error {
+  constructor() {
+    super(
+      'This "use cache" has a dynamic cache life that was propagated to its parent.'
+    )
+    this.name = 'Nested dynamic "use cache"'
+  }
+}

packages/next/src/server/use-cache/use-cache-wrapper.ts

@@ -59,7 +59,11 @@ import { DYNAMIC_EXPIRE, RUNTIME_PREFETCH_DYNAMIC_STALE } from './constants'
 import { NEXT_CACHE_ROOT_PARAM_TAG_ID } from '../../lib/constants'
 import type { CacheHandler } from '../lib/cache-handlers/types'
 import { getCacheHandler } from './handlers'
-import { UseCacheDeadlockError, UseCacheTimeoutError } from './use-cache-errors'
+import {
+  NestedDynamicUseCacheError,
+  UseCacheDeadlockError,
+  UseCacheTimeoutError,
+} from './use-cache-errors'
 import {
   createHangingInputAbortSignal,
   postponeWithTracking,
@@ -106,6 +110,15 @@ interface PublicCacheContext {
   readonly functionId: string
   /** The cache handler kind (first arg of `cache()`, e.g. 'default'). */
   readonly handlerKind: string
+  /**
+   * Eagerly captured at `cache()` entry, pointing at this invocation's call
+   * site. Only set when the outer is itself a public `'use cache'` (i.e. when
+   * this entry could become the propagated origin of a nested-dynamic cache
+   * error in the parent). When this cache resolves dynamic, this is copied into
+   * `outerWorkUnitStore.dynamicNestedCacheError` so the parent's error can use
+   * it as `cause`.
+   */
+  readonly dynamicNestedCacheError: Error | undefined
 }
 
 type CacheContext = PrivateCacheContext | PublicCacheContext
@@ -148,6 +161,7 @@ interface CacheResultMetadata {
   readonly readRootParamNames: ReadonlySet<string> | undefined
   readonly hasExplicitRevalidate: boolean | undefined
   readonly hasExplicitExpire: boolean | undefined
+  readonly dynamicNestedCacheError: Error | undefined
 }
 
 /**
@@ -268,15 +282,15 @@ const findSourceMapURL =
 const nestedCacheZeroRevalidateErrorMessage =
   `A "use cache" with zero \`revalidate\` is nested inside another "use cache" ` +
   `that has no explicit \`cacheLife\`, which is not allowed during ` +
-  `prerendering. Add \`cacheLife()\` to the outer \`"use cache"\` to choose ` +
+  `prerendering. Add \`cacheLife()\` to the outer "use cache" to choose ` +
   `whether it should be prerendered (with non-zero \`revalidate\`) or remain ` +
   `dynamic (with zero \`revalidate\`). Read more: ` +
   `https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife`
 
 const nestedCacheShortExpireErrorMessage =
   `A "use cache" with short \`expire\` (under 5 minutes) is nested inside ` +
   `another "use cache" that has no explicit \`cacheLife\`, which is not ` +
-  `allowed during prerendering. Add \`cacheLife()\` to the outer \`"use cache"\` ` +
+  `allowed during prerendering. Add \`cacheLife()\` to the outer "use cache" ` +
   `to choose whether it should be prerendered (with longer \`expire\`) or remain ` +
   `dynamic (with short \`expire\`). Read more: ` +
   `https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife`
@@ -381,6 +395,7 @@ function saveSharedCacheEntryToResumeDataCache(
       readRootParamNames: metadata.readRootParamNames,
       hasExplicitRevalidate: metadata.hasExplicitRevalidate,
       hasExplicitExpire: metadata.hasExplicitExpire,
+      dynamicNestedCacheError: metadata.dynamicNestedCacheError,
     }))
 
   prerenderResumeDataCache.cache.set(serializedCacheKey, rdcResult)
@@ -585,6 +600,7 @@ function createUseCacheStore(
       rootParams: outerWorkUnitStore.rootParams,
       readRootParamNames: new Set<string>(),
       outerOwnerStack: cacheContext.outerOwnerStack,
+      dynamicNestedCacheError: undefined,
     }
   }
 }
@@ -767,6 +783,17 @@ function propagateCacheEntryMetadata(
             cacheContext.outerWorkUnitStore.readRootParamNames.add(paramName)
           }
         }
+        // If this entry's cache life is dynamic, record this invocation as the
+        // origin to use as `cause` when the outer cache surfaces the
+        // nested-dynamic cache error. `??=` keeps the first occurrence so the
+        // cause points at the immediate dynamic child.
+        if (
+          cacheContext.dynamicNestedCacheError !== undefined &&
+          (metadata.revalidate === 0 || metadata.expire < DYNAMIC_EXPIRE)
+        ) {
+          cacheContext.outerWorkUnitStore.dynamicNestedCacheError ??=
+            cacheContext.dynamicNestedCacheError
+        }
       // fallthrough
       case 'private-cache':
       case 'prerender':
@@ -874,6 +901,15 @@ export interface CollectedCacheResult {
    * don't have this information.
    */
   readRootParamNames: ReadonlySet<string> | undefined
+  /**
+   * The `Error` carried up from the first nested public `'use cache'`
+   * invocation that propagated a dynamic cache life into this entry, captured
+   * eagerly at that inner invocation's `cache()` entry. Used as `cause` for the
+   * nested-dynamic cache error so the redbox can point at the inner invocation
+   * site, not just the outer one. Lives in-memory only — intentionally dropped
+   * from the serialized RDC because dynamic entries aren't serialized either.
+   */
+  dynamicNestedCacheError: Error | undefined
 }
 
 async function collectResult(
@@ -958,6 +994,12 @@ async function collectResult(
       innerCacheStore.type === 'cache'
         ? innerCacheStore.readRootParamNames
         : undefined,
+    // The store accumulates this from nested public caches that propagated a
+    // dynamic life into us.
+    dynamicNestedCacheError:
+      innerCacheStore.type === 'cache'
+        ? innerCacheStore.dynamicNestedCacheError
+        : undefined,
   }
 
   if (!cacheContext.skipPropagation) {
@@ -970,6 +1012,7 @@ async function collectResult(
       hasExplicitRevalidate: collected.hasExplicitRevalidate,
       hasExplicitExpire: collected.hasExplicitExpire,
       readRootParamNames: collected.readRootParamNames,
+      dynamicNestedCacheError: collected.dynamicNestedCacheError,
     })
 
     const cacheSignal = getCacheSignal(cacheContext.outerWorkUnitStore)
@@ -1338,12 +1381,14 @@ function cloneCacheResult(
       hasExplicitRevalidate: result.hasExplicitRevalidate,
       hasExplicitExpire: result.hasExplicitExpire,
       readRootParamNames: result.readRootParamNames,
+      dynamicNestedCacheError: result.dynamicNestedCacheError,
     },
     {
       entry: entryB,
       hasExplicitRevalidate: result.hasExplicitRevalidate,
       hasExplicitExpire: result.hasExplicitExpire,
       readRootParamNames: result.readRootParamNames,
+      dynamicNestedCacheError: result.dynamicNestedCacheError,
     },
   ]
 }
@@ -1560,12 +1605,36 @@ export async function cache(
         throw new InvariantError(
           `${expression} must not be used within a client component. Next.js should be preventing ${expression} from being allowed in client components statically, but did not in this case.`
         )
+      case 'cache': {
+        // Eagerly capture this invocation's call site while still synchronous
+        // in `cache()`. Used as `cause` of the nested-dynamic cache error
+        // when the outer cache (whose body never re-runs during the final
+        // prerender) throws. Only constructed when the parent is itself a
+        // public `'use cache'` — otherwise this entry can never propagate
+        // dynamism into that error and the allocation would be wasted. Private
+        // parents are intentionally excluded: `'use cache: private'` is
+        // dynamic-by-definition in prerendering and deferred to the runtime
+        // stage in dev requests, so a public cache nested inside one never
+        // triggers the throw upstream.
+        const dynamicNestedCacheError = new NestedDynamicUseCacheError()
+        Error.captureStackTrace(dynamicNestedCacheError, cache)
+        applyOwnerStack(dynamicNestedCacheError)
+        cacheContext = {
+          kind: 'public',
+          outerWorkUnitStore: workUnitStore,
+          skipPropagation: false,
+          outerOwnerStack,
+          functionId: id,
+          handlerKind: kind,
+          dynamicNestedCacheError,
+        }
+        break
+      }
       case 'prerender':
       case 'prerender-runtime':
       case 'prerender-ppr':
       case 'prerender-legacy':
       case 'request':
-      case 'cache':
       case 'private-cache':
       // TODO: We should probably forbid nesting "use cache" inside
       // unstable_cache. (fallthrough)
@@ -1578,6 +1647,7 @@ export async function cache(
           outerOwnerStack,
           functionId: id,
           handlerKind: kind,
+          dynamicNestedCacheError: undefined,
         }
         break
       default:
@@ -1988,7 +2058,9 @@ export async function cache(
               if (rdcResult.entry.revalidate === 0) {
                 if (rdcResult.hasExplicitRevalidate === false) {
                   throw wrapAsInvalidDynamicUsageError(
-                    new Error(nestedCacheZeroRevalidateErrorMessage)
+                    new Error(nestedCacheZeroRevalidateErrorMessage, {
+                      cause: rdcResult.dynamicNestedCacheError,
+                    })
                   )
                 }
                 debug?.(
@@ -1999,7 +2071,9 @@ export async function cache(
               } else {
                 if (rdcResult.hasExplicitExpire === false) {
                   throw wrapAsInvalidDynamicUsageError(
-                    new Error(nestedCacheShortExpireErrorMessage)
+                    new Error(nestedCacheShortExpireErrorMessage, {
+                      cause: rdcResult.dynamicNestedCacheError,
+                    })
                   )
                 }
                 debug?.(
@@ -2036,15 +2110,19 @@ export async function cache(
                   rdcResult.hasExplicitRevalidate === false
                 ) {
                   throw wrapAsInvalidDynamicUsageError(
-                    new Error(nestedCacheZeroRevalidateErrorMessage)
+                    new Error(nestedCacheZeroRevalidateErrorMessage, {
+                      cause: rdcResult.dynamicNestedCacheError,
+                    })
                   )
                 }
                 if (
                   rdcResult.entry.expire < DYNAMIC_EXPIRE &&
                   rdcResult.hasExplicitExpire === false
                 ) {
                   throw wrapAsInvalidDynamicUsageError(
-                    new Error(nestedCacheShortExpireErrorMessage)
+                    new Error(nestedCacheShortExpireErrorMessage, {
+                      cause: rdcResult.dynamicNestedCacheError,
+                    })
                   )
                 }
                 // We delay the cache here so that it doesn't resolve in the static task --
@@ -2154,6 +2232,7 @@ export async function cache(
           hasExplicitRevalidate: rdcResult.hasExplicitRevalidate,
           hasExplicitExpire: rdcResult.hasExplicitExpire,
           readRootParamNames: rdcResult.readRootParamNames,
+          dynamicNestedCacheError: rdcResult.dynamicNestedCacheError,
         })
 
         const [streamA, streamB] = rdcResult.entry.value.tee()
@@ -2685,6 +2764,7 @@ export async function cache(
               hasExplicitRevalidate: collected.hasExplicitRevalidate,
               hasExplicitExpire: collected.hasExplicitExpire,
               readRootParamNames: collected.readRootParamNames,
+              dynamicNestedCacheError: collected.dynamicNestedCacheError,
             }))
 
           const sharedCacheEntry = new SharedCacheEntry(
@@ -2720,6 +2800,8 @@ export async function cache(
             // set this to undefined here.
             hasExplicitRevalidate: undefined,
             hasExplicitExpire: undefined,
+            // The same applies to the dynamic nested cache error.
+            dynamicNestedCacheError: undefined,
           }
 
           maybePropagateCacheEntryMetadata(cacheContext, entryMetadata)
@@ -2746,6 +2828,7 @@ export async function cache(
                 hasExplicitRevalidate: entryMetadata.hasExplicitRevalidate,
                 hasExplicitExpire: entryMetadata.hasExplicitExpire,
                 readRootParamNames: entryMetadata.readRootParamNames,
+                dynamicNestedCacheError: entryMetadata.dynamicNestedCacheError,
               })
             )
           } else {