Unverified Commit 7b524fa2 authored by Zack Tanner's avatar Zack Tanner Committed by GitHub

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
parent 1b0113bf
---
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.
......@@ -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)
}
......@@ -27,6 +27,7 @@ export interface StaticGenerationStore {
forceStatic?: boolean
dynamicShouldError?: boolean
pendingRevalidates?: Promise<any>[]
postponeWasTriggered?: boolean
dynamicUsageDescription?: string
dynamicUsageStack?: string
......
......@@ -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)
......@@ -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 }
}
......
......@@ -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,12 +465,19 @@ 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',
......@@ -477,6 +485,7 @@ async function renderToHTMLOrFlightImpl(
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) {
......
......@@ -24,6 +24,7 @@ export function createErrorHandler({
errorLogger,
capturedErrors,
allCapturedErrors,
silenceLogger,
}: {
_source: string
dev?: boolean
......@@ -31,6 +32,7 @@ export function createErrorHandler({
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)
}
}
}
}
......
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
......@@ -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) {
......
import React from 'react'
export default function Root({ children }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import React from 'react'
import { cookies } from 'next/headers'
export default async function Page() {
try {
cookies()
} catch (err) {
throw new Error(
"Throwing a new error from 'no-suspense-boundary-re-throwing-error'"
)
}
return <div>Hello World</div>
}
import React from 'react'
import { cookies } from 'next/headers'
export default async function Page() {
try {
cookies()
} catch (err) {}
return <div>Hello World</div>
}
import React, { Suspense } from 'react'
import { cookies } from 'next/headers'
export default async function Page() {
return (
<Suspense fallback={<div>Loading...</div>}>
<Foobar />
</Suspense>
)
}
async function Foobar() {
try {
cookies()
} catch (err) {}
return null
}
import React, { Suspense } from 'react'
import { cookies } from 'next/headers'
export default async function Page() {
return (
<Suspense fallback={<div>Loading...</div>}>
<Foobar />
</Suspense>
)
}
async function Foobar() {
try {
cookies()
} catch (err) {
throw new Error('The original error was caught and rethrown.')
}
return null
}
import React, { Suspense } from 'react'
export default async function Page() {
return (
<Suspense fallback={<div>Loading...</div>}>
<Foobar />
</Suspense>
)
}
async function Foobar() {
throw new Error('Kaboom')
}
export default async function Page() {
throw new Error('Regular Prerender Error')
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
experimental: {
ppr: true,
},
}
module.exports = nextConfig
import { nextBuild } from 'next-test-utils'
describe('ppr build errors', () => {
let stderr: string
beforeAll(async () => {
stderr = (await nextBuild(__dirname, [], { stderr: true })).stderr
})
describe('within a suspense boundary', () => {
it('should fail the build for uncaught prerender errors', async () => {
expect(stderr).toContain(
'Error occurred prerendering page "/regular-error-suspense-boundary".'
)
})
describe('when a postpone call was made but missing postpone data', () => {
it('should fail the build', async () => {
expect(stderr).toContain(
'Postpone signal was caught while rendering /. Check to see if you\'re try/catching a Next.js API such as headers / cookies, or a fetch with "no-store".'
)
})
it('should fail the build & surface any errors that were thrown by user code', async () => {
// in the case of catching a postpone and throwing a new error, we log the error that the user threw to help with debugging
expect(stderr).toContain(
'Postpone signal was caught while rendering /re-throwing-error. Check to see if you\'re try/catching a Next.js API such as headers / cookies, or a fetch with "no-store".'
)
expect(stderr).toContain(
'The following error was thrown during build, and may help identify the source of the issue:'
)
expect(stderr).toContain(
'Error: The original error was caught and rethrown.'
)
// the regular pre-render error should not be thrown as well, as we've already logged a more specific error
expect(stderr).not.toContain(
'Error occurred prerendering page "/re-throwing-error"'
)
})
})
})
describe('outside of a suspense boundary', () => {
it('should fail the build for uncaught errors', async () => {
expect(stderr).toContain(
'Error occurred prerendering page "/regular-error".'
)
})
describe('when a postpone call was made but missing postpone data', () => {
it('should fail the build', async () => {
expect(stderr).toContain(
'Postpone signal was caught while rendering /no-suspense-boundary. Check to see if you\'re try/catching a Next.js API such as headers / cookies, or a fetch with "no-store".'
)
// the regular pre-render error should not be thrown as well, as we've already logged a more specific error
expect(stderr).not.toContain(
'Error occurred prerendering page "/no-suspense-boundary"'
)
})
it('should fail the build & surface any errors that were thrown by user code', async () => {
// in the case of catching a postpone and throwing a new error, we log the error that the user threw to help with debugging
expect(stderr).toContain(
'Postpone signal was caught while rendering /no-suspense-boundary-re-throwing-error. Check to see if you\'re try/catching a Next.js API such as headers / cookies, or a fetch with "no-store".'
)
expect(stderr).toContain(
'The following error was thrown during build, and may help identify the source of the issue:'
)
expect(stderr).toContain(
"Error: Throwing a new error from 'no-suspense-boundary-re-throwing-error'"
)
// the regular pre-render error should not be thrown as well, as we've already logged a more specific error
expect(stderr).not.toContain(
'Error occurred prerendering page "/no-suspense-boundary-re-throwing-error"'
)
})
})
})
})
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment