Unverified Commit 804cbc41 authored by Wyatt Johnson's avatar Wyatt Johnson Committed by GitHub

feat: add route context to prerender error messages (#82283)

### What?

This PR improves error debugging during prerendering by adding route
context to hanging promise rejection errors and related error messages.

### Why?

When developers encounter dynamic access issues during static
generation, the current error messages don't provide enough context
about which specific route is causing the problem. This makes debugging
difficult, especially in large applications with many routes.

By including route information in error messages, developers can quickly
identify the problematic route and resolve the issue more efficiently.

### How?

- Updates `makeHangingPromise` function signature to accept a `route`
parameter
- Modifies `HangingPromiseRejectionError` to include route information
in error messages
- Adds route context to all hanging promise calls across the codebase:
  - Dynamic rendering utilities
  - Fetch patching
  - Request APIs (cookies, headers, params, etc.)
  - Use cache wrapper
- Adds new error code 773 for missing workStore scenarios
- Ensures workStore validation where needed to prevent missing route
context

The changes are backward compatible and only enhance existing error
messages with additional debugging information.

### Fixing a bug

- Tests will be added in follow-up PR
- Error messages now include helpful route context for debugging

NAR-225
parent 49ac27c1
......@@ -770,5 +770,6 @@
"769": "createSearchParamsFromClient should not be called in a runtime prerender.",
"770": "createParamsFromClient should not be called in a runtime prerender.",
"771": "\\`%s\\` was called during a runtime prerender. Next.js should be preventing %s from being included in server components statically, but did not in this case.",
"772": "FetchStrategy.PPRRuntime should never be used when `experimental.clientSegmentCache` is disabled"
"772": "FetchStrategy.PPRRuntime should never be used when `experimental.clientSegmentCache` is disabled",
"773": "Missing workStore in createPrerenderParamsForClientSegment"
}
......@@ -585,8 +585,9 @@ export function annotateDynamicAccess(
}
export function useDynamicRouteParams(expression: string) {
const workStore = workAsyncStorage.getStore()
const workUnitStore = workUnitAsyncStorage.getStore()
if (workUnitStore) {
if (workStore && workUnitStore) {
switch (workUnitStore.type) {
case 'prerender-client':
case 'prerender': {
......@@ -595,19 +596,19 @@ export function useDynamicRouteParams(expression: string) {
// We are in a prerender with cacheComponents semantics. We are going to
// hang here and never resolve. This will cause the currently
// rendering component to effectively be a dynamic hole.
React.use(makeHangingPromise(workUnitStore.renderSignal, expression))
React.use(
makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
expression
)
)
}
break
}
case 'prerender-ppr': {
const fallbackParams = workUnitStore.fallbackRouteParams
if (fallbackParams && fallbackParams.size > 0) {
const workStore = workAsyncStorage.getStore()
if (!workStore) {
throw new InvariantError(
'Missing workStore in useDynamicRouteParams'
)
}
return postponeWithTracking(
workStore.route,
expression,
......
......@@ -13,9 +13,12 @@ const HANGING_PROMISE_REJECTION = 'HANGING_PROMISE_REJECTION'
class HangingPromiseRejectionError extends Error {
public readonly digest = HANGING_PROMISE_REJECTION
constructor(public readonly expression: string) {
constructor(
public readonly route: string,
public readonly expression: string
) {
super(
`During prerendering, ${expression} rejects when the prerender is complete. Typically these errors are handled by React but if you move ${expression} to a different context by using \`setTimeout\`, \`after\`, or similar functions you may observe this error and you should handle it in that context.`
`During prerendering, ${expression} rejects when the prerender is complete. Typically these errors are handled by React but if you move ${expression} to a different context by using \`setTimeout\`, \`after\`, or similar functions you may observe this error and you should handle it in that context. This occurred at route "${route}".`
)
}
}
......@@ -32,15 +35,16 @@ const abortListenersBySignal = new WeakMap<AbortSignal, AbortListeners>()
*/
export function makeHangingPromise<T>(
signal: AbortSignal,
route: string,
expression: string
): Promise<T> {
if (signal.aborted) {
return Promise.reject(new HangingPromiseRejectionError(expression))
return Promise.reject(new HangingPromiseRejectionError(route, expression))
} else {
const hangingPromise = new Promise<T>((_, reject) => {
const boundRejection = reject.bind(
null,
new HangingPromiseRejectionError(expression)
new HangingPromiseRejectionError(route, expression)
)
let currentListeners = abortListenersBySignal.get(signal)
if (currentListeners) {
......
......@@ -566,6 +566,7 @@ export function createPatchedFetcher(
return makeHangingPromise<Response>(
workUnitStore.renderSignal,
workStore.route,
'fetch()'
)
case 'prerender-ppr':
......@@ -678,6 +679,7 @@ export function createPatchedFetcher(
}
return makeHangingPromise<Response>(
workUnitStore.renderSignal,
workStore.route,
'fetch()'
)
case 'prerender-ppr':
......@@ -1027,6 +1029,7 @@ export function createPatchedFetcher(
}
return makeHangingPromise<Response>(
workUnitStore.renderSignal,
workStore.route,
'fetch()'
)
case 'prerender-ppr':
......@@ -1063,6 +1066,7 @@ export function createPatchedFetcher(
case 'prerender-runtime':
return makeHangingPromise<Response>(
workUnitStore.renderSignal,
workStore.route,
'fetch()'
)
case 'request':
......
......@@ -73,6 +73,7 @@ export function connection(): Promise<void> {
// stall at this point.
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`connection()`'
)
case 'prerender-ppr':
......
......@@ -5,7 +5,10 @@ import {
RequestCookiesAdapter,
} from '../web/spec-extension/adapters/request-cookies'
import { RequestCookies } from '../web/spec-extension/cookies'
import { workAsyncStorage } from '../app-render/work-async-storage.external'
import {
workAsyncStorage,
type WorkStore,
} from '../app-render/work-async-storage.external'
import {
throwForMissingRequestStore,
workUnitAsyncStorage,
......@@ -92,7 +95,7 @@ export function cookies(): Promise<ReadonlyRequestCookies> {
`Route ${workStore.route} used "cookies" inside a function cached with "unstable_cache(...)". Accessing Dynamic data sources inside a cache scope is not supported. If you need this data inside a cached function use "cookies" outside of the cached function and pass the required dynamic data in as an argument. See more info here: https://nextjs.org/docs/app/api-reference/functions/unstable_cache`
)
case 'prerender':
return makeHangingCookies(workUnitStore)
return makeHangingCookies(workStore, workUnitStore)
case 'prerender-client':
const exportName = '`cookies`'
throw new InvariantError(
......@@ -170,6 +173,7 @@ const CachedCookies = new WeakMap<
>()
function makeHangingCookies(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern
): Promise<ReadonlyRequestCookies> {
const cachedPromise = CachedCookies.get(prerenderStore)
......@@ -179,6 +183,7 @@ function makeHangingCookies(
const promise = makeHangingPromise<ReadonlyRequestCookies>(
prerenderStore.renderSignal,
workStore.route,
'`cookies()`'
)
CachedCookies.set(prerenderStore, promise)
......
......@@ -2,7 +2,10 @@ import {
HeadersAdapter,
type ReadonlyHeaders,
} from '../web/spec-extension/adapters/headers'
import { workAsyncStorage } from '../app-render/work-async-storage.external'
import {
workAsyncStorage,
type WorkStore,
} from '../app-render/work-async-storage.external'
import { throwForMissingRequestStore } from '../app-render/work-unit-async-storage.external'
import {
workUnitAsyncStorage,
......@@ -121,7 +124,7 @@ export function headers(): Promise<ReadonlyHeaders> {
switch (workUnitStore.type) {
case 'prerender':
case 'prerender-runtime':
return makeHangingHeaders(workUnitStore)
return makeHangingHeaders(workStore, workUnitStore)
case 'prerender-client':
const exportName = '`headers`'
throw new InvariantError(
......@@ -183,6 +186,7 @@ interface CacheLifetime {}
const CachedHeaders = new WeakMap<CacheLifetime, Promise<ReadonlyHeaders>>()
function makeHangingHeaders(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern
): Promise<ReadonlyHeaders> {
const cachedHeaders = CachedHeaders.get(prerenderStore)
......@@ -192,6 +196,7 @@ function makeHangingHeaders(
const promise = makeHangingPromise<ReadonlyHeaders>(
prerenderStore.renderSignal,
workStore.route,
'`headers()`'
)
CachedHeaders.set(prerenderStore, promise)
......
import type { WorkStore } from '../app-render/work-async-storage.external'
import {
workAsyncStorage,
type WorkStore,
} from '../app-render/work-async-storage.external'
import type { FallbackRouteParams } from './fallback-params'
import { ReflectAdapter } from '../web/spec-extension/adapters/reflect'
......@@ -151,6 +154,13 @@ export function createServerParamsForServerSegment(
export function createPrerenderParamsForClientSegment(
underlyingParams: Params
): Promise<Params> {
const workStore = workAsyncStorage.getStore()
if (!workStore) {
throw new InvariantError(
'Missing workStore in createPrerenderParamsForClientSegment'
)
}
const workUnitStore = workUnitAsyncStorage.getStore()
if (workUnitStore) {
switch (workUnitStore.type) {
......@@ -164,7 +174,11 @@ export function createPrerenderParamsForClientSegment(
// to consider the awaiting of this params object "dynamic". Since
// we are in cacheComponents mode we encode this as a promise that never
// resolves.
return makeHangingPromise(workUnitStore.renderSignal, '`params`')
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`params`'
)
}
}
}
......@@ -206,7 +220,11 @@ function createPrerenderParams(
// to consider the awaiting of this params object "dynamic". Since
// we are in cacheComponents mode we encode this as a promise that never
// resolves.
return makeHangingParams(underlyingParams, prerenderStore)
return makeHangingParams(
underlyingParams,
workStore,
prerenderStore
)
}
}
}
......@@ -298,6 +316,7 @@ const fallbackParamsProxyHandler: ProxyHandler<Promise<Params>> = {
function makeHangingParams(
underlyingParams: Params,
workStore: WorkStore,
prerenderStore: StaticPrerenderStoreModern
): Promise<Params> {
const cachedParams = CachedParams.get(underlyingParams)
......@@ -306,7 +325,11 @@ function makeHangingParams(
}
const promise = new Proxy(
makeHangingPromise<Params>(prerenderStore.renderSignal, '`params`'),
makeHangingPromise<Params>(
prerenderStore.renderSignal,
workStore.route,
'`params`'
),
fallbackParamsProxyHandler
)
......
......@@ -61,6 +61,7 @@ function createPrerenderPathname(
if (fallbackParams && fallbackParams.size > 0) {
return makeHangingPromise<string>(
prerenderStore.renderSignal,
workStore.route,
'`pathname`'
)
}
......
......@@ -88,6 +88,7 @@ function createPrerenderRootParams(
const promise = makeHangingPromise<Params>(
prerenderStore.renderSignal,
workStore.route,
'`unstable_rootParams`'
)
CachedParams.set(underlyingParams, promise)
......@@ -287,6 +288,7 @@ function createPrerenderRootParamPromise(
) {
return makeHangingPromise<ParamValue>(
prerenderStore.renderSignal,
workStore.route,
apiName
)
}
......
......@@ -139,7 +139,11 @@ export function createPrerenderSearchParamsForClientPage(
case 'prerender-client':
// We're prerendering in a mode that aborts (cacheComponents) and should stall
// the promise to ensure the RSC side is considered dynamic
return makeHangingPromise(workUnitStore.renderSignal, '`searchParams`')
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`searchParams`'
)
case 'prerender-runtime':
throw new InvariantError(
'createPrerenderSearchParamsForClientPage should not be called in a runtime prerender.'
......@@ -178,7 +182,7 @@ function createPrerenderSearchParams(
case 'prerender':
case 'prerender-client':
// We are in a cacheComponents (PPR or otherwise) prerender
return makeHangingSearchParams(prerenderStore)
return makeHangingSearchParams(workStore, prerenderStore)
case 'prerender-ppr':
case 'prerender-legacy':
// We are in a legacy static generation and need to interrupt the
......@@ -232,6 +236,7 @@ const CachedSearchParamsForUseCache = new WeakMap<
>()
function makeHangingSearchParams(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern
): Promise<SearchParams> {
const cachedSearchParams = CachedSearchParams.get(prerenderStore)
......@@ -241,6 +246,7 @@ function makeHangingSearchParams(
const promise = makeHangingPromise<SearchParams>(
prerenderStore.renderSignal,
workStore.route,
'`searchParams`'
)
......
......@@ -641,6 +641,7 @@ async function generateCacheEntryImpl(
// the "use cache" function dynamic.
const hangingPromise = makeHangingPromise<never>(
outerWorkUnitStore.renderSignal,
workStore.route,
abortSignal.reason
)
......@@ -835,7 +836,11 @@ export function cache(
switch (workUnitStore?.type) {
// "use cache: private" is dynamic in prerendering contexts.
case 'prerender':
return makeHangingPromise(workUnitStore.renderSignal, expression)
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
expression
)
case 'prerender-ppr':
return postponeWithTracking(
workStore.route,
......@@ -1082,6 +1087,7 @@ export function cache(
if (dynamicAccessAbortController.signal.aborted) {
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
dynamicAccessAbortController.signal.reason.message
)
}
......@@ -1147,6 +1153,7 @@ export function cache(
}
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
case 'prerender-runtime':
......@@ -1174,6 +1181,7 @@ export function cache(
}
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
case 'prerender':
......@@ -1226,6 +1234,7 @@ export function cache(
if (workUnitStore.allowEmptyStaticShell) {
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
}
......@@ -1325,6 +1334,7 @@ export function cache(
}
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
case 'prerender-runtime':
......
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