Unverified Commit 662c6d57 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Warn for non-deterministic `"use cache"` args during final prerender (#92820)

When a `"use cache"` function receives arguments that differ between the
cache warming phase and the final prerender, the cache key changes and
the Resume Data Cache (RDC) entry from the prospective prerender is
missed.

This can happen for various reasons, for example when concurrent async
operations push results into a shared array in non-deterministic order,
and that array is then passed as an argument to a cached function.

Without a `cacheSignal` to keep the render alive, the final prerender
aborts the cache entry generation, producing an incomplete RSC stream
that causes "Connection closed" errors.

This change detects that scenario (an RDC miss during the final
prerender where `cacheSignal` is `null`) and returns a hanging promise
instead of generating a broken cache entry. A warning is logged to help
developers identify the non-deterministic arguments. By making the
cached function a dynamic hole rather than erroring, the prerender can
still complete and produce at least a partial shell if there is a
Suspense boundary above. This affects both on-demand prerendering and
runtime prefetching.

To avoid false positives, cache keys that were intentionally skipped
during the prospective prerender (e.g. because the cached function
accessed fallback params) are tracked in a `dynamicCacheKeys` set on the
RDC. During the final prerender, a known dynamic key is returned as a
hanging promise early without logging a warning. This also serves as a
performance optimization, since it avoids trying to regenerate the
entry. This set is intentionally not serialized, as cache misses for
dynamic keys should generate fresh entries during the resume at request
time.
parent bf4de72c
......@@ -1160,5 +1160,6 @@
"1159": "\"unstable_instant\" is a route segment config and can only be used when the segment is a Server Component module. Remove the \"use client\" directive from \"%s\" to use this API.",
"1160": "Route \"%s\" cannot use \\`export const unstable_prefetch = ...\\` without enabling \\`cacheComponents\\`.",
"1161": "\"unstable_prefetch\" is a route segment config and can only be used when the segment is a Server Component module. Remove the \"use client\" directive from \"%s\" to use this API.",
"1162": "Route \"%s\" cannot use \\`export const unstable_instant = ...\\` without enabling \\`cacheComponents\\`."
"1162": "Route \"%s\" cannot use \\`export const unstable_instant = ...\\` without enabling \\`cacheComponents\\`.",
"1163": "Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic."
}
......@@ -118,7 +118,12 @@ describe('getDynamicHTMLPostponedState', () => {
expect(parsed).toEqual({
type: DynamicState.HTML,
data: [1, { [value]: value }],
renderResumeDataCache: createPrerenderResumeDataCache(),
renderResumeDataCache: {
cache: new Map(),
fetch: new Map(),
encryptedBoundArgs: new Map(),
decryptedBoundArgs: new Map(),
},
})
// The replacements have been replaced.
......@@ -148,7 +153,12 @@ describe('parsePostponedState', () => {
expect(parsed).toEqual({
type: DynamicState.HTML,
data: expect.any(Object),
renderResumeDataCache: createPrerenderResumeDataCache(),
renderResumeDataCache: {
cache: new Map(),
fetch: new Map(),
encryptedBoundArgs: new Map(),
decryptedBoundArgs: new Map(),
},
})
// Ensure that the replacement worked and removed all the placeholders.
......@@ -164,7 +174,12 @@ describe('parsePostponedState', () => {
expect(parsed).toEqual({
type: DynamicState.HTML,
data: expect.any(Object),
renderResumeDataCache: createPrerenderResumeDataCache(),
renderResumeDataCache: {
cache: new Map(),
fetch: new Map(),
encryptedBoundArgs: new Map(),
decryptedBoundArgs: new Map(),
},
})
})
......@@ -175,7 +190,12 @@ describe('parsePostponedState', () => {
// Ensure that it parsed it correctly.
expect(parsed).toEqual({
type: DynamicState.DATA,
renderResumeDataCache: createPrerenderResumeDataCache(),
renderResumeDataCache: {
cache: new Map(),
fetch: new Map(),
encryptedBoundArgs: new Map(),
decryptedBoundArgs: new Map(),
},
})
})
})
......@@ -140,9 +140,12 @@ describe('stringifyResumeDataCache', () => {
describe('parseResumeDataCache', () => {
it('parses an empty cache', () => {
expect(createRenderResumeDataCache('null', undefined)).toEqual(
createPrerenderResumeDataCache()
)
const parsed = createRenderResumeDataCache('null', undefined)
expect(parsed.cache).toEqual(new Map())
expect(parsed.fetch).toEqual(new Map())
expect(parsed.encryptedBoundArgs).toEqual(new Map())
expect(parsed.decryptedBoundArgs).toEqual(new Map())
expect(parsed.dynamicCacheKeys).toBeUndefined()
})
it('parses a filled cache', async () => {
......
......@@ -39,6 +39,16 @@ export interface RenderResumeDataCache {
* enforce immutability.
*/
readonly decryptedBoundArgs: Omit<DecryptedBoundArgsCacheStore, 'set'>
/**
* Serialized cache keys that were intentionally skipped during the
* prospective prerender (e.g. because the cached function accessed fallback
* params or other dynamic data). During the final prerender, a key in this
* set is returned as a hanging promise early, without attempting to look up
* or generate a cache entry. Optional because this field is intentionally not
* serialized and won't be present in deserialized caches.
*/
readonly dynamicCacheKeys?: ReadonlySet<string>
}
/**
......@@ -74,6 +84,20 @@ export interface PrerenderResumeDataCache {
* operations to build the cache during pre-rendering.
*/
readonly decryptedBoundArgs: DecryptedBoundArgsCacheStore
/**
* Tracks serialized cache keys that were intentionally skipped during the
* prospective prerender (e.g. because the cached function accessed fallback
* params or other dynamic data). During the final prerender, a key in this
* set is returned as a hanging promise early, without attempting to look up
* or generate a cache entry.
*
* This is intentionally not serialized. It is only used in-memory within a
* single prerender cycle (prospective to final). During the resume at request
* time, a cache miss for a dynamic key should generate a fresh entry rather
* than being short-circuited.
*/
readonly dynamicCacheKeys: Set<string>
}
type ResumeStoreSerialized = {
......@@ -156,6 +180,9 @@ export function createPrerenderResumeDataCache(
fetch: new Map(source.fetch),
encryptedBoundArgs: new Map(source.encryptedBoundArgs),
decryptedBoundArgs: new Map(source.decryptedBoundArgs),
dynamicCacheKeys: source.dynamicCacheKeys
? new Set(source.dynamicCacheKeys)
: new Set(),
}
} else {
return {
......@@ -163,6 +190,7 @@ export function createPrerenderResumeDataCache(
fetch: new Map(),
encryptedBoundArgs: new Map(),
decryptedBoundArgs: new Map(),
dynamicCacheKeys: new Set(),
}
}
}
......
......@@ -1550,6 +1550,32 @@ export async function cache(
const implicitTags = workUnitStore.implicitTags?.tags ?? []
if (renderResumeDataCache) {
// If this cache key was already determined to be dynamic during the
// prospective prerender (e.g. because it accessed fallback params), we
// return a hanging promise early to avoid trying to regenerate the entry,
// which would be aborted anyway.
if (renderResumeDataCache.dynamicCacheKeys?.has(serializedCacheKey)) {
switch (workUnitStore.type) {
case 'prerender':
case 'prerender-runtime':
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
case 'prerender-ppr':
case 'prerender-legacy':
case 'request':
case 'cache':
case 'private-cache':
case 'unstable-cache':
case 'generate-static-params':
break
default:
workUnitStore satisfies never
}
}
const cacheSignal = getCacheSignal(workUnitStore)
if (cacheSignal) {
......@@ -1802,14 +1828,38 @@ export async function cache(
// an async function, before being passed into the "use cache"
// function, which escapes the instrumentation.
if (workUnitStore.allowEmptyStaticShell) {
if (prerenderResumeDataCache) {
prerenderResumeDataCache.dynamicCacheKeys.add(serializedCacheKey)
}
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
}
break
// fallthrough
case 'prerender-runtime':
if (!cacheSignal) {
// This is the final prerender (cacheSignal is null), which means
// all caches should have been warmed during the prospective
// prerender. A cache miss here indicates that the cache key is
// non-deterministic (e.g. due to unstable array order in the
// arguments). Known dynamic keys (e.g. from fallback params) are
// already handled by the early return above. We return a hanging
// promise so this becomes a dynamic hole rather than generating a
// broken cache entry that gets aborted.
console.warn(
new Error(
`Unexpected cache miss after cache warming phase during prerendering. This is likely caused by non-deterministic arguments that differ between the cache warming phase and the final prerender phase (e.g. unstable array order). Ensure that arguments passed to cached functions are deterministic.`
)
)
return makeHangingPromise(
workUnitStore.renderSignal,
workStore.route,
'dynamic "use cache"'
)
}
break
case 'prerender-ppr':
case 'prerender-legacy':
case 'request':
......@@ -2006,6 +2056,9 @@ export async function cache(
)
if (result.type === 'prerender-dynamic') {
if (prerenderResumeDataCache) {
prerenderResumeDataCache.dynamicCacheKeys.add(serializedCacheKey)
}
return result.hangingPromise
}
......
......@@ -3421,11 +3421,12 @@ describe('Cache Components Errors', () => {
if (isDebugPrerender) {
expect(output).toMatchInlineSnapshot(`
"Error: Route "/use-cache-params/[slug]": Uncached data was accessed outside of <Suspense>. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/blocking-route
at Page [Server] (<anonymous>)
at main (<anonymous>)
at body (<anonymous>)
at html (<anonymous>)
at Root [Server] (<anonymous>)
at Page (app/use-cache-params/[slug]/page.tsx:1:16)
> 1 | export default async function Page({
| ^
2 | params,
3 | }: {
4 | params: Promise<{ slug: string }>
To debug the issue, start the app in development mode by running \`next dev\`, then open "/use-cache-params/[slug]" in your browser to investigate the error.
Error occurred prerendering page "/use-cache-params/[slug]". Read more: https://nextjs.org/docs/messages/prerender-error
......@@ -3447,16 +3448,12 @@ describe('Cache Components Errors', () => {
}
} else {
if (isDebugPrerender) {
expect(output).toMatchInlineSnapshot(`
"Error: Route "/use-cache-params/[slug]": Uncached data was accessed outside of <Suspense>. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/blocking-route
at Page [Server] (<anonymous>)
at <FIXME-library-internal>
To debug the issue, start the app in development mode by running \`next dev\`, then open "/use-cache-params/[slug]" in your browser to investigate the error.
Error occurred prerendering page "/use-cache-params/[slug]". Read more: https://nextjs.org/docs/messages/prerender-error
> Export encountered errors on 1 path:
/use-cache-params/[slug]/page: /use-cache-params/[slug]"
`)
// Webpack does not ignore the stack frame that points into
// Next.js internals, and is also flaky on resolving the exact
// location, so we don't assert on the stack frames here.
expect(output).toInclude(
'Error: Route "/use-cache-params/[slug]": Uncached data was accessed outside of <Suspense>. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/blocking-route'
)
} else {
expect(output).toMatchInlineSnapshot(`
"Error: Route "/use-cache-params/[slug]": Uncached data was accessed outside of <Suspense>. This delays the entire page from rendering, resulting in a slow user experience. Learn more: https://nextjs.org/docs/messages/blocking-route
......
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import Link from 'next/link'
import { Suspense, cacheSignal } from 'react'
import { setTimeout } from 'timers/promises'
import { cookies } from 'next/headers'
export const unstable_prefetch = 'runtime'
const callCounts = new Map<string, number>()
function getNonDeterministicItems(slug: string) {
// For testing purposes, this creates an artificial deterministic scenario
// that in real-world apps would usually be triggered by a race condition
// only sometimes (e.g. concurrent async operations pushing results into a
// shared array in non-deterministic order, and that array then being passed
// as an argument to a cached function).
//
// Call 1 (prospective prerender) warms the RDC entry for ['b','a'].
// Call 2+ (final prerender) uses ['a','b'], which produces a different cache
// key that misses the RDC.
const count = (callCounts.get(slug) ?? 0) + 1
callCounts.set(slug, count)
return count === 1 ? ['b', 'a'] : ['a', 'b']
}
async function getCachedValue(items: string[]) {
'use cache'
await setTimeout(1000)
return items.join(',')
}
async function Content({ slug }: { slug: string }) {
if (slug === 'known') {
// Awaiting cookies() causes this to suspend during build-time prerendering
// (cookies are not available at build time). During runtime prefetch,
// cookies are available so rendering continues past this point and hits the
// non-deterministic cached function.
await cookies()
}
const items = getNonDeterministicItems(slug)
try {
const value = await getCachedValue(items)
return (
<p id="cached">
{slug} {value}
</p>
)
} catch (error) {
// We only log and re-throw errors that occur while the render is still
// active. After the prerender is aborted, the hanging promise rejects with
// an expected error that we can safely ignore. This is the intended use of
// `React.cacheSignal()`. Userspace code should use it the same way to
// distinguish real errors from expected prerender teardown.
if (!cacheSignal()?.aborted) {
console.error('getCachedValue error:', error)
throw error
}
}
}
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
if (slug === 'with-runtime-prefetch') {
return <Link href="/known">Go to runtime-prefetchable page</Link>
}
return (
<Suspense fallback={<p>Loading...</p>}>
<Content slug={slug} />
</Suspense>
)
}
export function generateStaticParams() {
return [{ slug: 'known' }, { slug: 'with-runtime-prefetch' }]
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
import { nextTestSetup } from 'e2e-utils'
describe('use-cache-non-deterministic-args', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it('should warn about non-deterministic cache args during on-demand prerender', async () => {
const outputIndex = next.cliOutput.length
await next.browser('/unknown')
const output = next.cliOutput.slice(outputIndex)
expect(output).not.toContain('Connection closed')
expect(output).toContain(
'Unexpected cache miss after cache warming phase during prerendering'
)
})
it('should warn about non-deterministic cache args during runtime prefetch', async () => {
const outputIndex = next.cliOutput.length
let onRuntimePrefetchDone: () => void
const runtimePrefetchDone = new Promise<void>((resolve) => {
onRuntimePrefetchDone = resolve
})
// Visit /with-runtime-prefetch to render the Link. The link being visible
// in the viewport triggers a runtime prefetch for the /known route.
await next.browser('/with-runtime-prefetch', {
beforePageLoad(page) {
page.on('response', (res) => {
const url = new URL(res.url())
const request = res.request()
if (
url.pathname === '/known' &&
request.headers()['next-router-prefetch'] === '2'
) {
onRuntimePrefetchDone()
}
})
},
})
await runtimePrefetchDone
const output = next.cliOutput.slice(outputIndex)
expect(output).not.toContain('Connection closed')
expect(output).toContain(
'Unexpected cache miss after cache warming phase during prerendering'
)
})
})
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