ppr: fail static generation if postponed & missing postpone data (#57786)

When postpone is caught by user code, this will cause PPR not to properly prerender the static parts and thus we need to fail the build. This also adds some messaging about how to fix the error.

Prior to this change, catching code that would normally trigger `postpone ` would silently fail, but the build outputs would be incorrect as there's no postpone data available. 

Relands #57477 with additional tests & fixes

Author: ztanner

errors/ppr-postpone-error.mdx

@@ -0,0 +1,13 @@
+---
+title: Understanding the postpone error triggered during static generation
+---
+
+## Why This Error Occurred
+
+When Partial Prerendering (PPR) is enabled, using APIs that opt into Dynamic Rendering like `cookies`, `headers`, or `fetch` (such as with `cache: 'no-store'` or `revalidate: 0`) will cause Next.js to throw a special error to know which part of the page cannot be statically generated. If you catch this error, we will not be able to generate any static data, and your build will fail.
+
+## Possible Ways to Fix It
+
+To resolve this issue, ensure that you are not wrapping Next.js APIs that opt into dynamic rendering in a `try/catch` block.
+
+If you do wrap these APIs in a try/catch, make sure you re-throw the original error so it can be caught by Next.

packages/next/src/client/components/maybe-postpone.ts

@@ -18,5 +18,8 @@ export function maybePostpone(
   const React = require('react') as typeof import('react')
   if (typeof React.unstable_postpone !== 'function') return
 
+  // Keep track of if the postpone API has been called.
+  staticGenerationStore.postponeWasTriggered = true
+
   React.unstable_postpone(reason)
 }

packages/next/src/client/components/static-generation-async-storage.external.ts

@@ -27,6 +27,7 @@ export interface StaticGenerationStore {
   forceStatic?: boolean
   dynamicShouldError?: boolean
   pendingRevalidates?: Promise<any>[]
+  postponeWasTriggered?: boolean
 
   dynamicUsageDescription?: string
   dynamicUsageStack?: string

packages/next/src/export/helpers/is-dynamic-usage-error.ts

@@ -7,6 +7,4 @@ export const isDynamicUsageError = (err: any) =>
   err.digest === DYNAMIC_ERROR_CODE ||
   isNotFoundError(err) ||
   err.digest === NEXT_DYNAMIC_NO_SSR_CODE ||
-  isRedirectError(err) ||
-  // TODO: (wyattjoh) remove once we bump react
-  err.$$typeof === Symbol.for('react.postpone')
+  isRedirectError(err)

packages/next/src/export/worker.ts

@@ -33,6 +33,7 @@ import { exportPages } from './routes/pages'
 import { getParams } from './helpers/get-params'
 import { createIncrementalCache } from './helpers/create-incremental-cache'
 import { isPostpone } from '../server/lib/router-utils/is-postpone'
+import { isMissingPostponeDataError } from '../server/app-render/is-missing-postpone-error'
 
 const envConfig = require('../shared/lib/runtime-config.external')
 
@@ -306,10 +307,13 @@ async function exportPageImpl(
       fileWriter
     )
   } catch (err) {
-    console.error(
-      `\nError occurred prerendering page "${path}". Read more: https://nextjs.org/docs/messages/prerender-error\n` +
-        (isError(err) && err.stack ? err.stack : err)
-    )
+    // if this is a postpone error, it's logged elsewhere, so no need to log it again here
+    if (!isMissingPostponeDataError(err)) {
+      console.error(
+        `\nError occurred prerendering page "${path}". Read more: https://nextjs.org/docs/messages/prerender-error\n` +
+          (isError(err) && err.stack ? err.stack : err)
+      )
+    }
 
     return { error: true }
   }

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

@@ -61,7 +61,7 @@ import { validateURL } from './validate-url'
 import { createFlightRouterStateFromLoaderTree } from './create-flight-router-state-from-loader-tree'
 import { handleAction } from './action-handler'
 import { NEXT_DYNAMIC_NO_SSR_CODE } from '../../shared/lib/lazy-dynamic/no-ssr-error'
-import { warn } from '../../build/output/log'
+import { warn, error } from '../../build/output/log'
 import { appendMutableCookies } from '../web/spec-extension/adapters/request-cookies'
 import { createServerInsertedHTML } from './server-inserted-html'
 import { getRequiredScripts } from './required-scripts'
@@ -72,6 +72,7 @@ import { createComponentTree } from './create-component-tree'
 import { getAssetQueryString } from './get-asset-query-string'
 import { setReferenceManifestsSingleton } from './action-encryption-utils'
 import { createStaticRenderer } from './static/static-renderer'
+import { MissingPostponeDataError } from './is-missing-postpone-error'
 
 export type GetDynamicParamFromSegment = (
   // [slug] / [[slug]] / [...slug]
@@ -464,19 +465,27 @@ async function renderToHTMLOrFlightImpl(
   const capturedErrors: Error[] = []
   const allCapturedErrors: Error[] = []
   const isNextExport = !!renderOpts.nextExport
+  const { staticGenerationStore, requestStore } = baseCtx
+  const isStaticGeneration = staticGenerationStore.isStaticGeneration
+  // when static generation fails during PPR, we log the errors separately. We intentionally
+  // silence the error logger in this case to avoid double logging.
+  const silenceStaticGenerationErrors = renderOpts.ppr && isStaticGeneration
+
   const serverComponentsErrorHandler = createErrorHandler({
     _source: 'serverComponentsRenderer',
     dev,
     isNextExport,
     errorLogger: appDirDevErrorLogger,
     capturedErrors,
+    silenceLogger: silenceStaticGenerationErrors,
   })
   const flightDataRendererErrorHandler = createErrorHandler({
     _source: 'flightDataRenderer',
     dev,
     isNextExport,
     errorLogger: appDirDevErrorLogger,
     capturedErrors,
+    silenceLogger: silenceStaticGenerationErrors,
   })
   const htmlRendererErrorHandler = createErrorHandler({
     _source: 'htmlRenderer',
@@ -485,6 +494,7 @@ async function renderToHTMLOrFlightImpl(
     errorLogger: appDirDevErrorLogger,
     capturedErrors,
     allCapturedErrors,
+    silenceLogger: silenceStaticGenerationErrors,
   })
 
   patchFetch(ComponentMod)
@@ -520,7 +530,6 @@ async function renderToHTMLOrFlightImpl(
     )
   }
 
-  const { staticGenerationStore, requestStore } = baseCtx
   const { urlPathname } = staticGenerationStore
 
   staticGenerationStore.fetchMetrics = []
@@ -554,8 +563,6 @@ async function renderToHTMLOrFlightImpl(
     requestId = require('next/dist/compiled/nanoid').nanoid()
   }
 
-  const isStaticGeneration = staticGenerationStore.isStaticGeneration
-
   // During static generation we need to call the static generation bailout when reading searchParams
   const providedSearchParams = isStaticGeneration
     ? createSearchParamsBailoutProxy()
@@ -778,15 +785,6 @@ async function renderToHTMLOrFlightImpl(
           throw err
         }
 
-        // If there was a postponed error that escaped, it means that there was
-        // a postpone called without a wrapped suspense component.
-        if (err.$$typeof === Symbol.for('react.postpone')) {
-          // Ensure that we force the revalidation time to zero.
-          staticGenerationStore.revalidate = 0
-
-          throw err
-        }
-
         if (err.digest === NEXT_DYNAMIC_NO_SSR_CODE) {
           warn(
             `Entire page ${pagePath} deopted into client-side rendering. https://nextjs.org/docs/messages/deopted-into-client-rendering`,
@@ -1003,6 +1001,34 @@ async function renderToHTMLOrFlightImpl(
   if (staticGenerationStore.isStaticGeneration) {
     const htmlResult = await renderResult.toUnchunkedString(true)
 
+    if (
+      // if PPR is enabled
+      renderOpts.ppr &&
+      // and a call to `maybePostpone` happened
+      staticGenerationStore.postponeWasTriggered &&
+      // but there's no postpone state
+      !extraRenderResultMeta.postponed
+    ) {
+      // a call to postpone was made but was caught and not detected by Next.js. We should fail the build immediately
+      // as we won't be able to generate the static part
+      warn('')
+      error(
+        `Postpone signal was caught while rendering ${urlPathname}. Check to see if you're try/catching a Next.js API such as headers / cookies, or a fetch with "no-store". Learn more: https://nextjs.org/docs/messages/ppr-postpone-errors`
+      )
+
+      if (capturedErrors.length > 0) {
+        warn(
+          'The following error was thrown during build, and may help identify the source of the issue:'
+        )
+
+        error(capturedErrors[0])
+      }
+
+      throw new MissingPostponeDataError(
+        `An unexpected error occurred while prerendering ${urlPathname}. Please check the logs above for more details.`
+      )
+    }
+
     // if we encountered any unexpected errors during build
     // we fail the prerendering phase and the build
     if (capturedErrors.length > 0) {

packages/next/src/server/app-render/create-error-handler.tsx

@@ -24,13 +24,15 @@ export function createErrorHandler({
   errorLogger,
   capturedErrors,
   allCapturedErrors,
+  silenceLogger,
 }: {
   _source: string
   dev?: boolean
   isNextExport?: boolean
   errorLogger?: (err: any) => Promise<void>
   capturedErrors: Error[]
   allCapturedErrors?: Error[]
+  silenceLogger?: boolean
 }): ErrorHandler {
   return (err) => {
     if (allCapturedErrors) allCapturedErrors.push(err)
@@ -73,19 +75,21 @@ export function createErrorHandler({
         })
       }
 
-      if (errorLogger) {
-        errorLogger(err).catch(() => {})
-      } else {
-        // The error logger is currently not provided in the edge runtime.
-        // Use `log-app-dir-error` instead.
-        // It won't log the source code, but the error will be more useful.
-        if (process.env.NODE_ENV !== 'production') {
-          const { logAppDirError } =
-            require('../dev/log-app-dir-error') as typeof import('../dev/log-app-dir-error')
-          logAppDirError(err)
-        }
-        if (process.env.NODE_ENV === 'production') {
-          console.error(err)
+      if (!silenceLogger) {
+        if (errorLogger) {
+          errorLogger(err).catch(() => {})
+        } else {
+          // The error logger is currently not provided in the edge runtime.
+          // Use `log-app-dir-error` instead.
+          // It won't log the source code, but the error will be more useful.
+          if (process.env.NODE_ENV !== 'production') {
+            const { logAppDirError } =
+              require('../dev/log-app-dir-error') as typeof import('../dev/log-app-dir-error')
+            logAppDirError(err)
+          }
+          if (process.env.NODE_ENV === 'production') {
+            console.error(err)
+          }
         }
       }
     }

packages/next/src/server/app-render/is-missing-postpone-error.ts

@@ -0,0 +1,12 @@
+export const MISSING_POSTPONE_DATA_ERROR = 'MISSING_POSTPONE_DATA_ERROR'
+
+export class MissingPostponeDataError extends Error {
+  digest: typeof MISSING_POSTPONE_DATA_ERROR = MISSING_POSTPONE_DATA_ERROR
+
+  constructor(type: string) {
+    super(`Missing Postpone Data Error: ${type}`)
+  }
+}
+
+export const isMissingPostponeDataError = (err: any) =>
+  err.digest === MISSING_POSTPONE_DATA_ERROR

packages/next/src/server/base-server.ts

@@ -2682,7 +2682,7 @@ export default abstract class Server<ServerOptions extends Options = Options> {
       }
 
       if (isDataReq) {
-        // If this isn't a prefetch and this isn't a resume request, we  want to
+        // If this isn't a prefetch and this isn't a resume request, we want to
         // respond with the dynamic flight data. In the case that this is a
         // resume request the page data will already be dynamic.
         if (!isAppPrefetch && !resumed) {

test/e2e/app-dir/ppr-errors/app/layout.jsx

@@ -0,0 +1,9 @@
+import React from 'react'
+
+export default function Root({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}