Create errors lazily so that we can mutate their messages

eps1lon · eps1lon · commit 0b85dcb36c40 · 2026-02-19T18:47:48.000-08:00
diff --git a/packages/next/src/server/app-render/app-render.tsx b/packages/next/src/server/app-render/app-render.tsx
@@ -4132,14 +4132,14 @@ async function validateInstantConfigs(
       : false
   })
 
-  // Collect the first debug stack from segments with instant configs so we can
-  // pass it into validation state for setting `cause` on errors.
-  const debugInstantStack =
+  // Collect the first stack factory from segments with instant configs so we can
+  // pass it into validation state for creating errors with the config's stack trace.
+  const createInstantStack =
     segmentsWithInstantConfigs
       .map(
-        (segmentPath) => treeNodes.get(segmentPath)?.module?.debugInstantStack
+        (segmentPath) => treeNodes.get(segmentPath)?.module?.createInstantStack
       )
-      .find((stack): stack is Error => stack != null) ?? null
+      .find((factory): factory is () => Error => factory != null) ?? null
 
   const clientReferenceManifest = getClientReferenceManifest()
 
@@ -4181,7 +4181,7 @@ async function validateInstantConfigs(
       validationRouteTree,
       navigationParent,
       false, // use static stage for static segments
-      debugInstantStack
+      createInstantStack
     )
     if (initialResults.errors.length === 0) {
       debug?.(`  ✅ Validation successful`)
@@ -4201,7 +4201,7 @@ async function validateInstantConfigs(
           validationRouteTree,
           navigationParent,
           true, // use runtime stage for static segments instead
-          debugInstantStack
+          createInstantStack
         )
         if (runtimeResults.errors.length > 0) {
           // The errors remained in the runtime stage, so they were caused by a dynamic access.
@@ -4234,7 +4234,7 @@ async function validateInstantConfigNavigation(
   routeTree: InstantValidation.RouteTree,
   navigationParent: InstantValidation.SegmentPath,
   useRuntimeStageForPartialSegments: boolean,
-  debugInstantStack: Error | null
+  createInstantStack: (() => Error) | null
 ): Promise<{ dynamicHoleKind: DynamicHoleKind; errors: Array<unknown> }> {
   const { implicitTags, nonce, workStore } = ctx
   const isDebugChannelEnabled = !!ctx.renderOpts.setReactDebugChannel
@@ -4250,7 +4250,7 @@ async function validateInstantConfigNavigation(
   const preinitScripts = () => {}
   const { ServerInsertedHTMLProvider } = createServerInsertedHTML()
 
-  const dynamicValidation = createInstantValidationState(debugInstantStack)
+  const dynamicValidation = createInstantValidationState(createInstantStack)
   const boundaryState = createValidationBoundaryTracking()
 
   const finalClientPrerenderStore: PrerenderStore = {
diff --git a/packages/next/src/server/app-render/dynamic-rendering.ts b/packages/next/src/server/app-render/dynamic-rendering.ts
@@ -796,11 +796,11 @@ export type InstantValidationState = {
   dynamicErrors: Array<Error>
   validationPreventingErrors: Array<Error>
   thrownErrorsOutsideBoundary: Array<unknown>
-  debugInstantStack: Error | null
+  createInstantStack: (() => Error) | null
 }
 
 export function createInstantValidationState(
-  debugInstantStack: Error | null
+  createInstantStack: (() => Error) | null
 ): InstantValidationState {
   return {
     hasDynamicMetadata: false,
@@ -811,7 +811,7 @@ export function createInstantValidationState(
     dynamicErrors: [],
     validationPreventingErrors: [],
     thrownErrorsOutsideBoundary: [],
-    debugInstantStack,
+    createInstantStack,
   }
 }
 
@@ -836,7 +836,7 @@ export function trackDynamicHoleInNavigation(
     const error = createErrorWithComponentOrOwnerStack(
       message,
       componentStack,
-      dynamicValidation.debugInstantStack
+      dynamicValidation.createInstantStack
     )
     dynamicValidation.dynamicMetadata = error
     return
@@ -850,7 +850,7 @@ export function trackDynamicHoleInNavigation(
     const error = createErrorWithComponentOrOwnerStack(
       message,
       componentStack,
-      dynamicValidation.debugInstantStack
+      dynamicValidation.createInstantStack
     )
     dynamicValidation.dynamicErrors.push(error)
     return
@@ -880,7 +880,7 @@ export function trackDynamicHoleInNavigation(
       const error = createErrorWithComponentOrOwnerStack(
         message,
         componentStack,
-        dynamicValidation.debugInstantStack
+        dynamicValidation.createInstantStack
       )
       dynamicValidation.validationPreventingErrors.push(error)
       return
@@ -920,8 +920,11 @@ export function trackDynamicHoleInNavigation(
   if (clientDynamic.syncDynamicErrorWithStack) {
     // This task was the task that called the sync error.
     const syncError = clientDynamic.syncDynamicErrorWithStack
-    if (dynamicValidation.debugInstantStack && syncError.cause === undefined) {
-      syncError.cause = dynamicValidation.debugInstantStack
+    if (
+      dynamicValidation.createInstantStack !== null &&
+      syncError.cause === undefined
+    ) {
+      syncError.cause = dynamicValidation.createInstantStack()
     }
     dynamicValidation.dynamicErrors.push(syncError)
     return
@@ -935,7 +938,7 @@ export function trackDynamicHoleInNavigation(
   const error = createErrorWithComponentOrOwnerStack(
     message,
     componentStack,
-    dynamicValidation.debugInstantStack
+    dynamicValidation.createInstantStack
   )
   dynamicValidation.dynamicErrors.push(error)
   return
@@ -1083,14 +1086,15 @@ export function trackDynamicHoleInStaticShell(
 function createErrorWithComponentOrOwnerStack(
   message: string,
   componentStack: string,
-  cause: Error | null
+  createInstantStack: (() => Error) | null
 ) {
   const ownerStack =
     process.env.NODE_ENV !== 'production' && React.captureOwnerStack
       ? React.captureOwnerStack()
       : null
 
-  const error = new Error(message, cause !== null ? { cause } : {})
+  const cause = createInstantStack !== null ? createInstantStack() : null
+  const error = new Error(message, cause !== null ? { cause } : undefined)
   // TODO go back to owner stack here if available. This is temporarily using componentStack to get the right
   //
   error.stack = error.name + ': ' + message + (ownerStack || componentStack)
@@ -1245,31 +1249,29 @@ export function getNavigationDisallowedDynamicReasons(
   }
 
   if (boundaryState.renderedIds.size < boundaryState.expectedIds.size) {
-    const { thrownErrorsOutsideBoundary, debugInstantStack } = dynamicValidation
-    const causeOption = debugInstantStack ? { cause: debugInstantStack } : {}
+    const { thrownErrorsOutsideBoundary, createInstantStack } =
+      dynamicValidation
     if (thrownErrorsOutsideBoundary.length === 0) {
-      return [
-        new Error(
-          `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering for an unknown reason.`,
-          causeOption
-        ),
-      ]
+      const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering for an unknown reason.`
+      const error =
+        createInstantStack !== null ? createInstantStack() : new Error()
+      error.name = 'Error'
+      error.message = message
+      return [error]
     } else if (thrownErrorsOutsideBoundary.length === 1) {
-      return [
-        new Error(
-          `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to the following error.`,
-          causeOption
-        ),
-        thrownErrorsOutsideBoundary[0] as Error,
-      ]
+      const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to the following error.`
+      const error =
+        createInstantStack !== null ? createInstantStack() : new Error()
+      error.name = 'Error'
+      error.message = message
+      return [error, thrownErrorsOutsideBoundary[0] as Error]
     } else {
-      return [
-        new Error(
-          `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to one of the following errors.`,
-          causeOption
-        ),
-        ...(thrownErrorsOutsideBoundary as Error[]),
-      ]
+      const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to one of the following errors.`
+      const error =
+        createInstantStack !== null ? createInstantStack() : new Error()
+      error.name = 'Error'
+      error.message = message
+      return [error, ...(thrownErrorsOutsideBoundary as Error[])]
     }
   }
 
diff --git a/packages/next/src/server/app-render/instant-validation/instant-validation.tsx b/packages/next/src/server/app-render/instant-validation/instant-validation.tsx
@@ -86,7 +86,7 @@ export type RouteTree = {
     // TODO(instant-validation): We should know if a layout segment is shared
     instantConfig: InstantConfig | null
     conventionPath: string
-    debugInstantStack: Error | null
+    createInstantStack: (() => Error) | null
   }
 
   slots: { [parallelRouteKey: string]: RouteTree } | null
@@ -144,17 +144,17 @@ export async function findNavigationsToValidate(
       // TODO(restart-on-cache-miss): Does this work correctly for client page/layout modules?
       const instantConfig =
         (layoutOrPageMod as AppSegmentConfig).unstable_instant ?? null
-      const createInstantConfigStack: unknown = (layoutOrPageMod as any)
+      const rawFactory: unknown = (layoutOrPageMod as any)
         .__debugCreateInstantConfigStack
-      const debugInstantStack: Error | null =
-        typeof createInstantConfigStack === 'function'
-          ? createInstantConfigStack()
+      const createInstantStack: (() => Error) | null =
+        typeof rawFactory === 'function'
+          ? (rawFactory as () => Error)
           : null
       moduleInfo = {
         type: modType!,
         instantConfig,
         conventionPath: conventionPath!,
-        debugInstantStack,
+        createInstantStack,
       }
 
       if (isInsideParallelSlot) {
@@ -179,10 +179,13 @@ export async function findNavigationsToValidate(
             } else {
               const isRootLayout = parentLayoutPath === null
               if (isRootLayout && instantConfig.prefetch === 'runtime') {
-                throw new Error(
-                  `${conventionPath}: \`unstable_instant\` with mode 'runtime' is not supported in root layouts.`,
-                  debugInstantStack ? { cause: debugInstantStack } : {}
-                )
+                const message = `${conventionPath}: \`unstable_instant\` with mode 'runtime' is not supported in root layouts.`
+              const error =
+                createInstantStack !== null
+                  ? createInstantStack()
+                  : new Error()
+              error.message = message
+              throw error
               }
 
               const task: ValidationTask = {
diff --git a/test/e2e/app-dir/instant-validation/instant-validation.test.ts b/test/e2e/app-dir/instant-validation/instant-validation.test.ts
