[dynamicIO] Use owner stacks for dynamic validation errors (#81277)

With recent improvements in React, and after switching to the React
builds for Node.js in #81048, we can now generate better dynamic
validation error stacks in dev mode by utilizing owner stacks instead of
component stacks.

For async I/O, we're using the owner stack exclusively. For sync I/O
we're appending the owner stack to the call stack. In a future iteration
we might instead log the original error as-is where it occurs, and let
`patchErrorInspectNodeJS` handle the owner stack appending as a general
solution.

Additionally, we're now guiding users in the build-time error messages
to using `next dev` for further debugging of dynamic validation errors –
or, alternatively, using `next build --debug-prerender`.

closes NAR-149

Author: unstubbable

packages/next/src/export/index.ts

@@ -410,6 +410,14 @@ async function exportAppImpl(
       authInterrupts: !!nextConfig.experimental.authInterrupts,
     },
     reactMaxHeadersLength: nextConfig.reactMaxHeadersLength,
+    hasReadableErrorStacks:
+      nextConfig.experimental.serverSourceMaps === true &&
+      // TODO(NDX-531): Checking (and setting) the minify flags should be
+      // unnecessary once name mapping is fixed.
+      (process.env.TURBOPACK
+        ? nextConfig.experimental.turbopackMinify === false
+        : nextConfig.experimental.serverMinification === false) &&
+      nextConfig.experimental.enablePrerenderSourceMaps === true,
   }
 
   const { publicRuntimeConfig } = nextConfig

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

@@ -664,7 +664,7 @@ async function warmupDevRender(
 ): Promise<RenderResult> {
   const {
     clientReferenceManifest,
-    componentMod,
+    componentMod: ComponentMod,
     getDynamicParamFromSegment,
     implicitTags,
     renderOpts,
@@ -684,7 +684,7 @@ async function warmupDevRender(
   }
 
   const rootParams = getRootParams(
-    componentMod.tree,
+    ComponentMod.tree,
     getDynamicParamFromSegment
   )
 
@@ -725,6 +725,7 @@ async function warmupDevRender(
     prerenderResumeDataCache,
     renderResumeDataCache: null,
     hmrRefreshHash: req.cookies[NEXT_HMR_REFRESH_HASH_COOKIE],
+    captureOwnerStack: ComponentMod.captureOwnerStack,
   }
 
   const rscPayload = await workUnitAsyncStorage.run(
@@ -737,7 +738,7 @@ async function warmupDevRender(
   // which contains the subset React.
   workUnitAsyncStorage.run(
     prerenderStore,
-    componentMod.renderToReadableStream,
+    ComponentMod.renderToReadableStream,
     rscPayload,
     clientReferenceManifest.clientModules,
     {
@@ -2309,6 +2310,9 @@ async function spawnDynamicValidationInDev(
   // to cut the render off.
   const cacheSignal = new CacheSignal()
 
+  const captureOwnerStackClient = React.captureOwnerStack
+  const captureOwnerStackServer = ComponentMod.captureOwnerStack
+
   // The resume data cache here should use a fresh instance as it's
   // performing a fresh prerender. If we get to implementing the
   // prerendering of an already prerendered page, we should use the passed
@@ -2334,6 +2338,7 @@ async function spawnDynamicValidationInDev(
     prerenderResumeDataCache,
     renderResumeDataCache: null,
     hmrRefreshHash,
+    captureOwnerStack: captureOwnerStackServer,
   }
 
   // We're not going to use the result of this render because the only time it could be used
@@ -2448,6 +2453,7 @@ async function spawnDynamicValidationInDev(
       prerenderResumeDataCache,
       renderResumeDataCache: null,
       hmrRefreshHash: undefined,
+      captureOwnerStack: captureOwnerStackClient,
     }
 
     const prerender = (
@@ -2541,6 +2547,7 @@ async function spawnDynamicValidationInDev(
     prerenderResumeDataCache,
     renderResumeDataCache: null,
     hmrRefreshHash,
+    captureOwnerStack: captureOwnerStackServer,
   }
 
   const finalAttemptRSCPayload = await workUnitAsyncStorage.run(
@@ -2611,6 +2618,7 @@ async function spawnDynamicValidationInDev(
     prerenderResumeDataCache,
     renderResumeDataCache: null,
     hmrRefreshHash,
+    captureOwnerStack: captureOwnerStackClient,
   }
 
   let dynamicValidation = createDynamicValidationState()
@@ -2643,7 +2651,7 @@ async function spawnDynamicValidationInDev(
                   const componentStack = errorInfo.componentStack
                   if (typeof componentStack === 'string') {
                     trackAllowedDynamicAccess(
-                      workStore.route,
+                      workStore,
                       componentStack,
                       dynamicValidation,
                       clientDynamicTracking
@@ -2957,6 +2965,7 @@ async function prerenderToStream(
         prerenderResumeDataCache,
         renderResumeDataCache,
         hmrRefreshHash: undefined,
+        captureOwnerStack: undefined, // Not available in production.
       })
 
       // We're not going to use the result of this render because the only time it could be used
@@ -3064,6 +3073,7 @@ async function prerenderToStream(
           prerenderResumeDataCache,
           renderResumeDataCache,
           hmrRefreshHash: undefined,
+          captureOwnerStack: undefined, // Not available in production.
         }
 
         const prerender = (
@@ -3157,6 +3167,7 @@ async function prerenderToStream(
         prerenderResumeDataCache,
         renderResumeDataCache,
         hmrRefreshHash: undefined,
+        captureOwnerStack: undefined, // Not available in production.
       })
 
       const finalAttemptRSCPayload = await workUnitAsyncStorage.run(
@@ -3229,6 +3240,7 @@ async function prerenderToStream(
         prerenderResumeDataCache,
         renderResumeDataCache,
         hmrRefreshHash: undefined,
+        captureOwnerStack: undefined, // Not available in production.
       }
 
       let clientIsDynamic = false
@@ -3265,7 +3277,7 @@ async function prerenderToStream(
                     ).componentStack
                     if (typeof componentStack === 'string') {
                       trackAllowedDynamicAccess(
-                        workStore.route,
+                        workStore,
                         componentStack,
                         dynamicValidation,
                         clientDynamicTracking

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

@@ -616,7 +616,7 @@ const hasViewportRegex = new RegExp(
 const hasOutletRegex = new RegExp(`\\n\\s+at ${OUTLET_BOUNDARY_NAME}[\\n\\s]`)
 
 export function trackAllowedDynamicAccess(
-  route: string,
+  workStore: WorkStore,
   componentStack: string,
   dynamicValidation: DynamicValidationState,
   clientDynamic: DynamicTrackingState
@@ -648,19 +648,25 @@ export function trackAllowedDynamicAccess(
     )
     return
   } else {
-    const message = `Route "${route}": A component accessed data, headers, params, searchParams, or a short-lived cache without a Suspense boundary nor a "use cache" above it. We don't have the exact line number added to error messages yet but you can see which component in the stack below. See more info: https://nextjs.org/docs/messages/next-prerender-missing-suspense`
-    const error = createErrorWithComponentStack(message, componentStack)
+    const message = `Route "${workStore.route}": A component accessed data, headers, params, searchParams, or a short-lived cache without a Suspense boundary nor a "use cache" above it. See more info: https://nextjs.org/docs/messages/next-prerender-missing-suspense`
+    const error = createErrorWithComponentOrOwnerStack(message, componentStack)
     dynamicValidation.dynamicErrors.push(error)
     return
   }
 }
 
-function createErrorWithComponentStack(
+/**
+ * In dev mode, we prefer using the owner stack, otherwise the provided
+ * component stack is used.
+ */
+function createErrorWithComponentOrOwnerStack(
   message: string,
   componentStack: string
 ) {
+  const ownerStack =
+    process.env.NODE_ENV !== 'production' ? React.captureOwnerStack() : null
   const error = new Error(message)
-  error.stack = 'Error: ' + message + componentStack
+  error.stack = error.name + ': ' + message + (ownerStack ?? componentStack)
   return error
 }
 
@@ -670,14 +676,30 @@ export enum PreludeState {
   Errored = 2,
 }
 
+function logDisallowedDynamicError(workStore: WorkStore, error: Error): void {
+  console.error(error)
+
+  if (!workStore.dev) {
+    if (workStore.hasReadableErrorStacks) {
+      console.error(
+        `To get a more detailed stack trace and pinpoint the issue, start the app in development mode by running \`next dev\`, then open "${workStore.route}" in your browser to investigate the error.`
+      )
+    } else {
+      console.error(`To get a more detailed stack trace and pinpoint the issue, try one of the following:
+  - Start the app in development mode by running \`next dev\`, then open "${workStore.route}" in your browser to investigate the error.
+  - Rerun the production build with \`next build --debug-prerender\` to generate better stack traces.`)
+    }
+  }
+}
+
 export function throwIfDisallowedDynamic(
   workStore: WorkStore,
   prelude: PreludeState,
   dynamicValidation: DynamicValidationState,
   serverDynamic: DynamicTrackingState
 ): void {
   if (workStore.invalidDynamicUsageError) {
-    console.error(workStore.invalidDynamicUsageError)
+    logDisallowedDynamicError(workStore, workStore.invalidDynamicUsageError)
     throw new StaticGenBailoutError()
   }
 
@@ -692,9 +714,11 @@ export function throwIfDisallowedDynamic(
     if (serverDynamic.syncDynamicErrorWithStack) {
       // There is no shell and the server did something sync dynamic likely
       // leading to an early termination of the prerender before the shell
-      // could be completed.
-      console.error(serverDynamic.syncDynamicErrorWithStack)
-      // We terminate the build/validating render
+      // could be completed. We terminate the build/validating render.
+      logDisallowedDynamicError(
+        workStore,
+        serverDynamic.syncDynamicErrorWithStack
+      )
       throw new StaticGenBailoutError()
     }
 
@@ -704,7 +728,7 @@ export function throwIfDisallowedDynamic(
     const dynamicErrors = dynamicValidation.dynamicErrors
     if (dynamicErrors.length > 0) {
       for (let i = 0; i < dynamicErrors.length; i++) {
-        console.error(dynamicErrors[i])
+        logDisallowedDynamicError(workStore, dynamicErrors[i])
       }
 
       throw new StaticGenBailoutError()

packages/next/src/server/app-render/entry-base.ts

@@ -10,6 +10,9 @@ export {
 // eslint-disable-next-line import/no-extraneous-dependencies
 export { unstable_prerender as prerender } from 'react-server-dom-webpack/static'
 
+// eslint-disable-next-line import/no-extraneous-dependencies
+export { captureOwnerStack } from 'react'
+
 export { default as LayoutRouter } from '../../client/components/layout-router'
 export { default as RenderFromTemplateContext } from '../../client/components/render-from-template-context'
 export { workAsyncStorage } from '../app-render/work-async-storage.external'

packages/next/src/server/app-render/types.ts

@@ -263,6 +263,14 @@ export interface RenderOptsPartial {
    */
   isDebugDynamicAccesses?: boolean
 
+  /**
+   * This is true when:
+   * - source maps are generated
+   * - source maps are applied
+   * - minification is disabled
+   */
+  hasReadableErrorStacks?: boolean
+
   /**
    * The maximum length of the headers that are emitted by React and added to
    * the response.

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

@@ -36,6 +36,15 @@ export interface WorkStore {
 
   readonly isOnDemandRevalidate?: boolean
   readonly isBuildTimePrerendering?: boolean
+
+  /**
+   * This is true when:
+   * - source maps are generated
+   * - source maps are applied
+   * - minification is disabled
+   */
+  readonly hasReadableErrorStacks?: boolean
+
   readonly isRevalidate?: boolean
 
   forceDynamic?: boolean

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

@@ -142,6 +142,11 @@ export interface PrerenderStoreModern extends CommonWorkUnitStore {
    * subsequent dynamic render.
    */
   readonly hmrRefreshHash: string | undefined
+
+  /**
+   * Only available in dev mode.
+   */
+  readonly captureOwnerStack: undefined | (() => string | null)
 }
 
 export interface PrerenderStorePPR extends CommonWorkUnitStore {

packages/next/src/server/async-storage/work-store.ts

@@ -65,6 +65,7 @@ export type WorkStoreContext = {
     | 'isDraftMode'
     | 'isDebugDynamicAccesses'
     | 'dev'
+    | 'hasReadableErrorStacks'
   > &
     RequestLifecycleOpts &
     Partial<Pick<RenderOpts, 'reactLoadableManifest'>>
@@ -123,6 +124,7 @@ export function createWorkStore({
     cacheLifeProfiles: renderOpts.cacheLifeProfiles,
     isRevalidate: renderOpts.isRevalidate,
     isBuildTimePrerendering: renderOpts.nextExport,
+    hasReadableErrorStacks: renderOpts.hasReadableErrorStacks,
     fetchCache: renderOpts.fetchCache,
     isOnDemandRevalidate: renderOpts.isOnDemandRevalidate,
 

packages/next/src/server/node-environment-extensions/utils.tsx

@@ -44,8 +44,22 @@ export function io(expression: string, type: ApiType) {
                 'Unknown expression type in abortOnSynchronousPlatformIOAccess.'
               )
           }
+
           const errorWithStack = new Error(message)
 
+          if (process.env.NODE_ENV !== 'production') {
+            const ownerStack = workUnitStore.captureOwnerStack!()
+
+            if (ownerStack) {
+              // TODO: Instead of stitching the stacks here, we should log the
+              // original error as-is when it occurs (i.e. here), and let
+              // `patchErrorInspect` handle adding the owner stack, instead of
+              // logging it deferred in the `LogSafely` component via
+              // `throwIfDisallowedDynamic`.
+              applyOwnerStack(errorWithStack, ownerStack)
+            }
+          }
+
           abortOnSynchronousPlatformIOAccess(
             workStore.route,
             expression,
@@ -63,3 +77,23 @@ export function io(expression: string, type: ApiType) {
     }
   }
 }
+
+function applyOwnerStack(error: Error, ownerStack: string) {
+  let stack = ownerStack
+
+  if (error.stack) {
+    const frames: string[] = []
+
+    for (const frame of error.stack.split('\n').slice(1)) {
+      if (frame.includes('react_stack_bottom_frame')) {
+        break
+      }
+
+      frames.push(frame)
+    }
+
+    stack = '\n' + frames.join('\n') + stack
+  }
+
+  error.stack = error.name + ': ' + error.message + stack
+}

packages/next/src/server/route-modules/app-route/module.ts

@@ -401,6 +401,7 @@ export class AppRouteRouteModule extends RouteModule<
               prerenderResumeDataCache: null,
               renderResumeDataCache: null,
               hmrRefreshHash: undefined,
+              captureOwnerStack: undefined,
             })
 
           let prospectiveResult
@@ -492,6 +493,7 @@ export class AppRouteRouteModule extends RouteModule<
             prerenderResumeDataCache: null,
             renderResumeDataCache: null,
             hmrRefreshHash: undefined,
+            captureOwnerStack: undefined,
           })
 
           let responseHandled = false