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 @@ ...@@ -770,5 +770,6 @@
"769": "createSearchParamsFromClient should not be called in a runtime prerender.", "769": "createSearchParamsFromClient should not be called in a runtime prerender.",
"770": "createParamsFromClient 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.", "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( ...@@ -585,8 +585,9 @@ export function annotateDynamicAccess(
} }
export function useDynamicRouteParams(expression: string) { export function useDynamicRouteParams(expression: string) {
const workStore = workAsyncStorage.getStore()
const workUnitStore = workUnitAsyncStorage.getStore() const workUnitStore = workUnitAsyncStorage.getStore()
if (workUnitStore) { if (workStore && workUnitStore) {
switch (workUnitStore.type) { switch (workUnitStore.type) {
case 'prerender-client': case 'prerender-client':
case 'prerender': { case 'prerender': {
...@@ -595,19 +596,19 @@ export function useDynamicRouteParams(expression: string) { ...@@ -595,19 +596,19 @@ export function useDynamicRouteParams(expression: string) {
// We are in a prerender with cacheComponents semantics. We are going to // We are in a prerender with cacheComponents semantics. We are going to
// hang here and never resolve. This will cause the currently // hang here and never resolve. This will cause the currently
// rendering component to effectively be a dynamic hole. // rendering component to effectively be a dynamic hole.
React.use(makeHangingPromise(workUnitStore.renderSignal, expression)) React.use(
makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
expression
)
)
} }
break break
} }
case 'prerender-ppr': { case 'prerender-ppr': {
const fallbackParams = workUnitStore.fallbackRouteParams const fallbackParams = workUnitStore.fallbackRouteParams
if (fallbackParams && fallbackParams.size > 0) { if (fallbackParams && fallbackParams.size > 0) {
const workStore = workAsyncStorage.getStore()
if (!workStore) {
throw new InvariantError(
'Missing workStore in useDynamicRouteParams'
)
}
return postponeWithTracking( return postponeWithTracking(
workStore.route, workStore.route,
expression, expression,
......
...@@ -13,9 +13,12 @@ const HANGING_PROMISE_REJECTION = 'HANGING_PROMISE_REJECTION' ...@@ -13,9 +13,12 @@ const HANGING_PROMISE_REJECTION = 'HANGING_PROMISE_REJECTION'
class HangingPromiseRejectionError extends Error { class HangingPromiseRejectionError extends Error {
public readonly digest = HANGING_PROMISE_REJECTION public readonly digest = HANGING_PROMISE_REJECTION
constructor(public readonly expression: string) { constructor(
public readonly route: string,
public readonly expression: string
) {
super( 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>() ...@@ -32,15 +35,16 @@ const abortListenersBySignal = new WeakMap<AbortSignal, AbortListeners>()
*/ */
export function makeHangingPromise<T>( export function makeHangingPromise<T>(
signal: AbortSignal, signal: AbortSignal,
route: string,
expression: string expression: string
): Promise<T> { ): Promise<T> {
if (signal.aborted) { if (signal.aborted) {
return Promise.reject(new HangingPromiseRejectionError(expression)) return Promise.reject(new HangingPromiseRejectionError(route, expression))
} else { } else {
const hangingPromise = new Promise<T>((_, reject) => { const hangingPromise = new Promise<T>((_, reject) => {
const boundRejection = reject.bind( const boundRejection = reject.bind(
null, null,
new HangingPromiseRejectionError(expression) new HangingPromiseRejectionError(route, expression)
) )
let currentListeners = abortListenersBySignal.get(signal) let currentListeners = abortListenersBySignal.get(signal)
if (currentListeners) { if (currentListeners) {
......
...@@ -566,6 +566,7 @@ export function createPatchedFetcher( ...@@ -566,6 +566,7 @@ export function createPatchedFetcher(
return makeHangingPromise<Response>( return makeHangingPromise<Response>(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'fetch()' 'fetch()'
) )
case 'prerender-ppr': case 'prerender-ppr':
...@@ -678,6 +679,7 @@ export function createPatchedFetcher( ...@@ -678,6 +679,7 @@ export function createPatchedFetcher(
} }
return makeHangingPromise<Response>( return makeHangingPromise<Response>(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'fetch()' 'fetch()'
) )
case 'prerender-ppr': case 'prerender-ppr':
...@@ -1027,6 +1029,7 @@ export function createPatchedFetcher( ...@@ -1027,6 +1029,7 @@ export function createPatchedFetcher(
} }
return makeHangingPromise<Response>( return makeHangingPromise<Response>(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'fetch()' 'fetch()'
) )
case 'prerender-ppr': case 'prerender-ppr':
...@@ -1063,6 +1066,7 @@ export function createPatchedFetcher( ...@@ -1063,6 +1066,7 @@ export function createPatchedFetcher(
case 'prerender-runtime': case 'prerender-runtime':
return makeHangingPromise<Response>( return makeHangingPromise<Response>(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'fetch()' 'fetch()'
) )
case 'request': case 'request':
......
...@@ -73,6 +73,7 @@ export function connection(): Promise<void> { ...@@ -73,6 +73,7 @@ export function connection(): Promise<void> {
// stall at this point. // stall at this point.
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'`connection()`' '`connection()`'
) )
case 'prerender-ppr': case 'prerender-ppr':
......
...@@ -5,7 +5,10 @@ import { ...@@ -5,7 +5,10 @@ import {
RequestCookiesAdapter, RequestCookiesAdapter,
} from '../web/spec-extension/adapters/request-cookies' } from '../web/spec-extension/adapters/request-cookies'
import { RequestCookies } from '../web/spec-extension/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 { import {
throwForMissingRequestStore, throwForMissingRequestStore,
workUnitAsyncStorage, workUnitAsyncStorage,
...@@ -92,7 +95,7 @@ export function cookies(): Promise<ReadonlyRequestCookies> { ...@@ -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` `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': case 'prerender':
return makeHangingCookies(workUnitStore) return makeHangingCookies(workStore, workUnitStore)
case 'prerender-client': case 'prerender-client':
const exportName = '`cookies`' const exportName = '`cookies`'
throw new InvariantError( throw new InvariantError(
...@@ -170,6 +173,7 @@ const CachedCookies = new WeakMap< ...@@ -170,6 +173,7 @@ const CachedCookies = new WeakMap<
>() >()
function makeHangingCookies( function makeHangingCookies(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern prerenderStore: PrerenderStoreModern
): Promise<ReadonlyRequestCookies> { ): Promise<ReadonlyRequestCookies> {
const cachedPromise = CachedCookies.get(prerenderStore) const cachedPromise = CachedCookies.get(prerenderStore)
...@@ -179,6 +183,7 @@ function makeHangingCookies( ...@@ -179,6 +183,7 @@ function makeHangingCookies(
const promise = makeHangingPromise<ReadonlyRequestCookies>( const promise = makeHangingPromise<ReadonlyRequestCookies>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
'`cookies()`' '`cookies()`'
) )
CachedCookies.set(prerenderStore, promise) CachedCookies.set(prerenderStore, promise)
......
...@@ -2,7 +2,10 @@ import { ...@@ -2,7 +2,10 @@ import {
HeadersAdapter, HeadersAdapter,
type ReadonlyHeaders, type ReadonlyHeaders,
} from '../web/spec-extension/adapters/headers' } 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 { throwForMissingRequestStore } from '../app-render/work-unit-async-storage.external'
import { import {
workUnitAsyncStorage, workUnitAsyncStorage,
...@@ -121,7 +124,7 @@ export function headers(): Promise<ReadonlyHeaders> { ...@@ -121,7 +124,7 @@ export function headers(): Promise<ReadonlyHeaders> {
switch (workUnitStore.type) { switch (workUnitStore.type) {
case 'prerender': case 'prerender':
case 'prerender-runtime': case 'prerender-runtime':
return makeHangingHeaders(workUnitStore) return makeHangingHeaders(workStore, workUnitStore)
case 'prerender-client': case 'prerender-client':
const exportName = '`headers`' const exportName = '`headers`'
throw new InvariantError( throw new InvariantError(
...@@ -183,6 +186,7 @@ interface CacheLifetime {} ...@@ -183,6 +186,7 @@ interface CacheLifetime {}
const CachedHeaders = new WeakMap<CacheLifetime, Promise<ReadonlyHeaders>>() const CachedHeaders = new WeakMap<CacheLifetime, Promise<ReadonlyHeaders>>()
function makeHangingHeaders( function makeHangingHeaders(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern prerenderStore: PrerenderStoreModern
): Promise<ReadonlyHeaders> { ): Promise<ReadonlyHeaders> {
const cachedHeaders = CachedHeaders.get(prerenderStore) const cachedHeaders = CachedHeaders.get(prerenderStore)
...@@ -192,6 +196,7 @@ function makeHangingHeaders( ...@@ -192,6 +196,7 @@ function makeHangingHeaders(
const promise = makeHangingPromise<ReadonlyHeaders>( const promise = makeHangingPromise<ReadonlyHeaders>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
'`headers()`' '`headers()`'
) )
CachedHeaders.set(prerenderStore, promise) 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 type { FallbackRouteParams } from './fallback-params'
import { ReflectAdapter } from '../web/spec-extension/adapters/reflect' import { ReflectAdapter } from '../web/spec-extension/adapters/reflect'
...@@ -151,6 +154,13 @@ export function createServerParamsForServerSegment( ...@@ -151,6 +154,13 @@ export function createServerParamsForServerSegment(
export function createPrerenderParamsForClientSegment( export function createPrerenderParamsForClientSegment(
underlyingParams: Params underlyingParams: Params
): Promise<Params> { ): Promise<Params> {
const workStore = workAsyncStorage.getStore()
if (!workStore) {
throw new InvariantError(
'Missing workStore in createPrerenderParamsForClientSegment'
)
}
const workUnitStore = workUnitAsyncStorage.getStore() const workUnitStore = workUnitAsyncStorage.getStore()
if (workUnitStore) { if (workUnitStore) {
switch (workUnitStore.type) { switch (workUnitStore.type) {
...@@ -164,7 +174,11 @@ export function createPrerenderParamsForClientSegment( ...@@ -164,7 +174,11 @@ export function createPrerenderParamsForClientSegment(
// to consider the awaiting of this params object "dynamic". Since // to consider the awaiting of this params object "dynamic". Since
// we are in cacheComponents mode we encode this as a promise that never // we are in cacheComponents mode we encode this as a promise that never
// resolves. // resolves.
return makeHangingPromise(workUnitStore.renderSignal, '`params`') return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'`params`'
)
} }
} }
} }
...@@ -206,7 +220,11 @@ function createPrerenderParams( ...@@ -206,7 +220,11 @@ function createPrerenderParams(
// to consider the awaiting of this params object "dynamic". Since // to consider the awaiting of this params object "dynamic". Since
// we are in cacheComponents mode we encode this as a promise that never // we are in cacheComponents mode we encode this as a promise that never
// resolves. // resolves.
return makeHangingParams(underlyingParams, prerenderStore) return makeHangingParams(
underlyingParams,
workStore,
prerenderStore
)
} }
} }
} }
...@@ -298,6 +316,7 @@ const fallbackParamsProxyHandler: ProxyHandler<Promise<Params>> = { ...@@ -298,6 +316,7 @@ const fallbackParamsProxyHandler: ProxyHandler<Promise<Params>> = {
function makeHangingParams( function makeHangingParams(
underlyingParams: Params, underlyingParams: Params,
workStore: WorkStore,
prerenderStore: StaticPrerenderStoreModern prerenderStore: StaticPrerenderStoreModern
): Promise<Params> { ): Promise<Params> {
const cachedParams = CachedParams.get(underlyingParams) const cachedParams = CachedParams.get(underlyingParams)
...@@ -306,7 +325,11 @@ function makeHangingParams( ...@@ -306,7 +325,11 @@ function makeHangingParams(
} }
const promise = new Proxy( const promise = new Proxy(
makeHangingPromise<Params>(prerenderStore.renderSignal, '`params`'), makeHangingPromise<Params>(
prerenderStore.renderSignal,
workStore.route,
'`params`'
),
fallbackParamsProxyHandler fallbackParamsProxyHandler
) )
......
...@@ -61,6 +61,7 @@ function createPrerenderPathname( ...@@ -61,6 +61,7 @@ function createPrerenderPathname(
if (fallbackParams && fallbackParams.size > 0) { if (fallbackParams && fallbackParams.size > 0) {
return makeHangingPromise<string>( return makeHangingPromise<string>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
'`pathname`' '`pathname`'
) )
} }
......
...@@ -88,6 +88,7 @@ function createPrerenderRootParams( ...@@ -88,6 +88,7 @@ function createPrerenderRootParams(
const promise = makeHangingPromise<Params>( const promise = makeHangingPromise<Params>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
'`unstable_rootParams`' '`unstable_rootParams`'
) )
CachedParams.set(underlyingParams, promise) CachedParams.set(underlyingParams, promise)
...@@ -287,6 +288,7 @@ function createPrerenderRootParamPromise( ...@@ -287,6 +288,7 @@ function createPrerenderRootParamPromise(
) { ) {
return makeHangingPromise<ParamValue>( return makeHangingPromise<ParamValue>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
apiName apiName
) )
} }
......
...@@ -139,7 +139,11 @@ export function createPrerenderSearchParamsForClientPage( ...@@ -139,7 +139,11 @@ export function createPrerenderSearchParamsForClientPage(
case 'prerender-client': case 'prerender-client':
// We're prerendering in a mode that aborts (cacheComponents) and should stall // We're prerendering in a mode that aborts (cacheComponents) and should stall
// the promise to ensure the RSC side is considered dynamic // 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': case 'prerender-runtime':
throw new InvariantError( throw new InvariantError(
'createPrerenderSearchParamsForClientPage should not be called in a runtime prerender.' 'createPrerenderSearchParamsForClientPage should not be called in a runtime prerender.'
...@@ -178,7 +182,7 @@ function createPrerenderSearchParams( ...@@ -178,7 +182,7 @@ function createPrerenderSearchParams(
case 'prerender': case 'prerender':
case 'prerender-client': case 'prerender-client':
// We are in a cacheComponents (PPR or otherwise) prerender // We are in a cacheComponents (PPR or otherwise) prerender
return makeHangingSearchParams(prerenderStore) return makeHangingSearchParams(workStore, prerenderStore)
case 'prerender-ppr': case 'prerender-ppr':
case 'prerender-legacy': case 'prerender-legacy':
// We are in a legacy static generation and need to interrupt the // We are in a legacy static generation and need to interrupt the
...@@ -232,6 +236,7 @@ const CachedSearchParamsForUseCache = new WeakMap< ...@@ -232,6 +236,7 @@ const CachedSearchParamsForUseCache = new WeakMap<
>() >()
function makeHangingSearchParams( function makeHangingSearchParams(
workStore: WorkStore,
prerenderStore: PrerenderStoreModern prerenderStore: PrerenderStoreModern
): Promise<SearchParams> { ): Promise<SearchParams> {
const cachedSearchParams = CachedSearchParams.get(prerenderStore) const cachedSearchParams = CachedSearchParams.get(prerenderStore)
...@@ -241,6 +246,7 @@ function makeHangingSearchParams( ...@@ -241,6 +246,7 @@ function makeHangingSearchParams(
const promise = makeHangingPromise<SearchParams>( const promise = makeHangingPromise<SearchParams>(
prerenderStore.renderSignal, prerenderStore.renderSignal,
workStore.route,
'`searchParams`' '`searchParams`'
) )
......
...@@ -641,6 +641,7 @@ async function generateCacheEntryImpl( ...@@ -641,6 +641,7 @@ async function generateCacheEntryImpl(
// the "use cache" function dynamic. // the "use cache" function dynamic.
const hangingPromise = makeHangingPromise<never>( const hangingPromise = makeHangingPromise<never>(
outerWorkUnitStore.renderSignal, outerWorkUnitStore.renderSignal,
workStore.route,
abortSignal.reason abortSignal.reason
) )
...@@ -835,7 +836,11 @@ export function cache( ...@@ -835,7 +836,11 @@ export function cache(
switch (workUnitStore?.type) { switch (workUnitStore?.type) {
// "use cache: private" is dynamic in prerendering contexts. // "use cache: private" is dynamic in prerendering contexts.
case 'prerender': case 'prerender':
return makeHangingPromise(workUnitStore.renderSignal, expression) return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
expression
)
case 'prerender-ppr': case 'prerender-ppr':
return postponeWithTracking( return postponeWithTracking(
workStore.route, workStore.route,
...@@ -1082,6 +1087,7 @@ export function cache( ...@@ -1082,6 +1087,7 @@ export function cache(
if (dynamicAccessAbortController.signal.aborted) { if (dynamicAccessAbortController.signal.aborted) {
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
dynamicAccessAbortController.signal.reason.message dynamicAccessAbortController.signal.reason.message
) )
} }
...@@ -1147,6 +1153,7 @@ export function cache( ...@@ -1147,6 +1153,7 @@ export function cache(
} }
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"' 'dynamic "use cache"'
) )
case 'prerender-runtime': case 'prerender-runtime':
...@@ -1174,6 +1181,7 @@ export function cache( ...@@ -1174,6 +1181,7 @@ export function cache(
} }
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"' 'dynamic "use cache"'
) )
case 'prerender': case 'prerender':
...@@ -1226,6 +1234,7 @@ export function cache( ...@@ -1226,6 +1234,7 @@ export function cache(
if (workUnitStore.allowEmptyStaticShell) { if (workUnitStore.allowEmptyStaticShell) {
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"' 'dynamic "use cache"'
) )
} }
...@@ -1325,6 +1334,7 @@ export function cache( ...@@ -1325,6 +1334,7 @@ export function cache(
} }
return makeHangingPromise( return makeHangingPromise(
workUnitStore.renderSignal, workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"' 'dynamic "use cache"'
) )
case 'prerender-runtime': 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