Restore dev-mode cache-fill timeout for `'use cache'`

When `'use cache'` fills during `next dev`, there was no timeout, so a
stalled fill could hang the request indefinitely. This change restores a
dev-mode cache-fill timeout that fires 50 seconds after the fill starts,
matching the 50s timeout we already have during prerender. The timer
sets `workStore.invalidDynamicUsageError` to a `UseCacheTimeoutError`
and aborts the signal passed to React's `renderToReadableStream`, which
errors the cache stream. From there the existing handling of
`invalidDynamicUsageError` in app-render surfaces the error in the
Redbox and the CLI output without any additional plumbing.

Prior to PR #85747, `spawnDynamicValidationInDev` reused the prerender
store and inherited the prerender cache timeout as a side effect. After
that change the validation became staged-rendering based and the timeout
stopped applying to dev renders. This PR closes that gap.

The timeout is skipped when the render is already in the Dynamic stage,
which mirrors prerender, where caches past `await connection()` aren't
executed at all. The check is written as exact equality on
`RenderStage.Dynamic` rather than a numeric `< Dynamic` comparison
because `RenderStage.Abandoned` is numerically higher than Dynamic but
semantically represents an aborted initial prospective render whose
pending caches still need to be timed out while the outer flow awaits
`cacheSignal.cacheReady()`. The 50s duration is shared with the
prerender path via a new `USE_CACHE_FILL_TIMEOUT_MS` constant and
carries a TODO to derive it from the user-configurable
`staticPageGenerationTimeout`.

The tests model a realistic migration hazard: a module-scoped in-flight
fetch dedupe loader (the hand-rolled variant of the documented
`React.cache`-based preload pattern) joined by a `'use cache'` function.
That configuration deadlocks because the outer fetch is parked on the
Dynamic stage in dev, or returns an intentionally hanging promise during
prerender, and the cache never fills.
parent a03b8eee
...@@ -101,6 +101,19 @@ interface PublicCacheContext { ...@@ -101,6 +101,19 @@ interface PublicCacheContext {
type CacheContext = PrivateCacheContext | PublicCacheContext type CacheContext = PrivateCacheContext | PublicCacheContext
// The maximum time we allow a `'use cache'` entry to fill. After this, we
// assume the fill is stalled — either on hanging input to the cached function,
// or on hanging I/O inside of it — and de-opt with an error.
//
// For prerender, this needs to be lower than the general build timeout
// (`staticPageGenerationTimeout`, default 60s) so the cache-fill error surfaces
// before the build worker kills the page.
//
// TODO: Derive this from the configured `staticPageGenerationTimeout` instead
// of hard-coding it, so users who raise or lower the build timeout get a
// matching cache-fill timeout.
const USE_CACHE_FILL_TIMEOUT_MS = 50_000
type CacheKeyParts = type CacheKeyParts =
| [buildId: string, id: string, args: unknown[]] | [buildId: string, id: string, args: unknown[]]
| [buildId: string, id: string, args: unknown[], hmrRefreshHash: string] | [buildId: string, id: string, args: unknown[], hmrRefreshHash: string]
...@@ -1051,18 +1064,17 @@ async function generateCacheEntryImpl( ...@@ -1051,18 +1064,17 @@ async function generateCacheEntryImpl(
) )
let stream: ReadableStream<Uint8Array> let stream: ReadableStream<Uint8Array>
let devTimeoutSignal: AbortSignal | undefined
let devTimeoutTimer: ReturnType<typeof setTimeout> | undefined
switch (outerWorkUnitStore.type) { switch (outerWorkUnitStore.type) {
case 'prerender-runtime': case 'prerender-runtime':
case 'prerender': case 'prerender':
const timeoutAbortController = new AbortController() const timeoutAbortController = new AbortController()
// If we're prerendering, we give you 50 seconds to fill a cache entry.
// Otherwise we assume you stalled on hanging input and de-opt. This needs
// to be lower than just the general timeout of 60 seconds.
const timer = setTimeout(() => { const timer = setTimeout(() => {
workStore.invalidDynamicUsageError = timeoutError workStore.invalidDynamicUsageError = timeoutError
timeoutAbortController.abort(timeoutError) timeoutAbortController.abort(timeoutError)
}, 50000) }, USE_CACHE_FILL_TIMEOUT_MS)
const dynamicAccessAbortSignal = const dynamicAccessAbortSignal =
dynamicAccessAsyncStorage.getStore()?.abortController.signal dynamicAccessAsyncStorage.getStore()?.abortController.signal
...@@ -1140,6 +1152,30 @@ async function generateCacheEntryImpl( ...@@ -1140,6 +1152,30 @@ async function generateCacheEntryImpl(
) { ) {
await new Promise((resolve) => setTimeout(resolve)) await new Promise((resolve) => setTimeout(resolve))
} }
if (process.env.NODE_ENV === 'development') {
// Start a cache-fill timeout so a hanging `'use cache'` entry surfaces
// the same error in dev as during prerender. Cleared when
// pendingCacheResult settles.
//
// Only skip the timeout when we're exactly in the Dynamic stage. That
// mirrors prerender, where caches guarded by e.g. `await connection()`
// aren't executed at all. We can't use `< RenderStage.Dynamic` here
// because `RenderStage.Abandoned` is numerically higher than Dynamic,
// but semantically it means the initial prospective render was aborted
// while caches are still pending — the outer flow then awaits
// `cacheSignal.cacheReady()`, so we need the timer to break a potential
// deadlock.
const stagedRendering = outerWorkUnitStore.stagedRendering
if (stagedRendering?.currentStage !== RenderStage.Dynamic) {
const devTimeoutAbortController = new AbortController()
devTimeoutSignal = devTimeoutAbortController.signal
devTimeoutTimer = setTimeout(() => {
workStore.invalidDynamicUsageError = timeoutError
devTimeoutAbortController.abort(timeoutError)
}, USE_CACHE_FILL_TIMEOUT_MS)
}
}
// fallthrough // fallthrough
case 'prerender-ppr': case 'prerender-ppr':
case 'prerender-legacy': case 'prerender-legacy':
...@@ -1153,6 +1189,7 @@ async function generateCacheEntryImpl( ...@@ -1153,6 +1189,7 @@ async function generateCacheEntryImpl(
{ {
environmentName: 'Cache', environmentName: 'Cache',
filterStackFrame, filterStackFrame,
signal: devTimeoutSignal,
temporaryReferences, temporaryReferences,
onError: handleError, onError: handleError,
} }
...@@ -1171,7 +1208,11 @@ async function generateCacheEntryImpl( ...@@ -1171,7 +1208,11 @@ async function generateCacheEntryImpl(
innerCacheStore, innerCacheStore,
startTime, startTime,
errors errors
) ).finally(() => {
if (devTimeoutTimer !== undefined) {
clearTimeout(devTimeoutTimer)
}
})
if (process.env.NODE_ENV === 'development') { if (process.env.NODE_ENV === 'development') {
// Name the stream for React DevTools. // Name the stream for React DevTools.
......
import { connection } from 'next/server'
import { ReactNode, Suspense } from 'react'
// A cache fill in the Dynamic stage (after `connection()`) should not be
// subject to the dev fill timeout. This mirrors prerender, where caches
// past `connection()` aren't executed at all and therefore not subject to
// the timeout handling either. The sleep is intentionally longer than the
// 50s timeout so the test fails if the timer isn't cleared.
async function Cached(): Promise<ReactNode> {
'use cache'
await new Promise((resolve) => setTimeout(resolve, 52_000))
return <p id="cached">cached</p>
}
async function Dynamic(): Promise<ReactNode> {
await connection()
return <Cached />
}
export default function Page() {
return (
<Suspense fallback="Loading...">
<Dynamic />
</Suspense>
)
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import { cookies } from 'next/headers'
import { Suspense } from 'react'
import { getData, preload } from '../shared'
const sharedUrl =
'https://next-data-api-endpoint.vercel.app/api/random?page=runtime'
async function getCachedData(): Promise<string> {
'use cache'
// Joins the outer fetch via the module-scoped dedupe map (see note in
// ../shared.ts).
return getData(sharedUrl).then((res) => res.text())
}
async function Cached() {
// The timeout error must also be shown in the Next.js DevTools when the
// invocation is wrapped in a try/catch.
try {
const data = await getCachedData()
return <p id="result">{data}</p>
} catch (error) {
return <p id="result">Error: {error.message}</p>
}
}
async function Runtime() {
await cookies()
// Simulate another part of the tree (e.g. a sibling component or a shared
// data loader) kicking off the same fetch in outer scope before `Cached`
// runs.
preload(sharedUrl)
return <Cached />
}
export default function Page() {
return (
<Suspense fallback="Loading...">
<Runtime />
</Suspense>
)
}
// This module simulates a realistic migration hazard. The documented "preload"
// pattern (see the "Preloading data" section of the
// caching-without-cache-components guide in the Next.js docs) wraps the loader
// in `React.cache`, so its store is tied to the ALS snapshot — `'use cache'`
// bodies run in a clean snapshot and miss, re-executing the loader in cache
// scope. That path is safe during migration.
//
// What's modeled here is the common-in-the-wild variant that uses a
// module-scoped `Map` instead of `React.cache`. The map lives above ALS, so a
// `'use cache'` body joining it reuses the outer-scope promise (request scope
// or prerender scope) — a promise that was never meant to resolve for the
// cache:
// - During prerendering, an uncached fetch in the outer scope returns a
// hanging promise that intentionally never resolves.
// - In dev, the outer fetch is parked on the Dynamic stage, which can't
// advance until the cache fills. The cache awaits the outer fetch via the
// shared loader, so neither can make progress.
// In both cases, the cache never fills and times out.
const pendingFetches = new Map<string, Promise<Response>>()
export function getData(url: string): Promise<Response> {
let promise = pendingFetches.get(url)
if (!promise) {
promise = fetch(url)
pendingFetches.set(url, promise)
promise.then(
() => pendingFetches.delete(url),
() => pendingFetches.delete(url)
)
}
return promise
}
// "Preload" primes the shared loader without awaiting so later callers reuse
// the stored promise.
export function preload(url: string): void {
void getData(url)
}
import { getData, preload } from '../shared'
const sharedUrl =
'https://next-data-api-endpoint.vercel.app/api/random?page=static'
async function getCachedData(): Promise<string> {
'use cache'
// Joins the outer fetch via the module-scoped dedupe map (see note in
// ../shared.ts).
return getData(sharedUrl).then((res) => res.text())
}
async function Cached() {
// The timeout error must also be shown in the Next.js DevTools when the
// invocation is wrapped in a try/catch.
try {
const data = await getCachedData()
return <p id="result">{data}</p>
} catch (error) {
return <p id="result">Error: {error.message}</p>
}
}
export default function Page() {
// Simulate another part of the tree (e.g. a sibling component or a shared
// data loader) kicking off the same fetch in outer scope before `Cached`
// runs.
preload(sharedUrl)
return <Cached />
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import stripAnsi from 'strip-ansi'
const expectedTimeoutErrorMessage =
'Filling a cache during prerender timed out, likely because request-specific arguments such as params, searchParams, cookies() or dynamic data were used inside "use cache".'
describe('use-cache-hanging', () => {
const { next, isNextDev, skipped, isTurbopack } = nextTestSetup({
files: __dirname,
skipDeployment: true,
skipStart: process.env.NEXT_TEST_MODE !== 'dev',
})
if (skipped) {
return
}
if (isNextDev) {
describe('when a "use cache" fill hangs in the static stage', () => {
it('should show an error toast after a timeout', async () => {
const outputIndex = next.cliOutput.length
const browser = await next.browser('/static')
await expect(browser).toDisplayRedbox(`
{
"code": "E394",
"description": "Filling a cache during prerender timed out, likely because request-specific arguments such as params, searchParams, cookies() or dynamic data were used inside "use cache".",
"environmentLabel": null,
"label": "Runtime Error",
"source": "app/static/page.tsx (6:1) @ getCachedData
> 6 | async function getCachedData(): Promise<string> {
| ^",
"stack": [
"getCachedData app/static/page.tsx (6:1)",
"Cached app/static/page.tsx (18:24)",
"stringify <anonymous>",
],
}
`)
const cliOutput = stripAnsi(next.cliOutput.slice(outputIndex))
expect(cliOutput).toContain(`Error: ${expectedTimeoutErrorMessage}
at getCachedData (app/static/page.tsx:6:1)`)
}, 180_000)
})
describe('when a "use cache" fill hangs in the runtime stage', () => {
it('should show an error toast after a timeout', async () => {
const outputIndex = next.cliOutput.length
const browser = await next.browser('/runtime')
await expect(browser).toDisplayRedbox(`
{
"code": "E394",
"description": "Filling a cache during prerender timed out, likely because request-specific arguments such as params, searchParams, cookies() or dynamic data were used inside "use cache".",
"environmentLabel": null,
"label": "Runtime Error",
"source": "app/runtime/page.tsx (8:1) @ getCachedData
> 8 | async function getCachedData(): Promise<string> {
| ^",
"stack": [
"getCachedData app/runtime/page.tsx (8:1)",
"Cached app/runtime/page.tsx (20:24)",
],
}
`)
const cliOutput = stripAnsi(next.cliOutput.slice(outputIndex))
expect(cliOutput).toContain(`Error: ${expectedTimeoutErrorMessage}
at getCachedData (app/runtime/page.tsx:8:1)`)
}, 180_000)
})
describe('when a "use cache" performs long-running I/O in the dynamic stage', () => {
it('should not time out', async () => {
const outputIndex = next.cliOutput.length
const browser = await next.browser('/dynamic')
await expect(browser.elementByCss('#cached').text()).resolves.toBe(
'cached'
)
const cliOutput = stripAnsi(next.cliOutput.slice(outputIndex))
expect(cliOutput).not.toContain(expectedTimeoutErrorMessage)
}, 180_000)
})
} else {
describe('when a "use cache" fill hangs during prerendering', () => {
it('should fail the build with a timeout error', async () => {
try {
await next.start()
} catch {
// expected
}
if (isTurbopack) {
expect(next.cliOutput)
.toContain(`Error: ${expectedTimeoutErrorMessage}
at <unknown> (app/static/page.tsx:6:1)`)
} else {
// Webpack production builds don't have source maps by default.
expect(next.cliOutput).toContain(expectedTimeoutErrorMessage)
}
}, 180_000)
})
}
})
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