[PPF] Fix self-hosted 500s when empty fallback shells miss the cache

A self-hosted `next start` app using `cacheComponents`,
`partialPrefetching`, and a custom `cacheHandler` can return HTTP 500
when the handler misses both a generated route and its generic fallback.
The server then tries to prerender the generic shell on demand.

In the reproduction, `app/layout.tsx` defines the root layout, and
`app/[locale]/page.tsx` defines `locale` beneath it as an ordinary
dynamic parameter. `generateStaticParams()` supplies `/en` and `/fr`,
but the page awaits `params` outside `<Suspense>`. This leaves the
generic `/[locale]` HTML shell empty. The build permits that result
because it prerenders the concrete routes. The custom handler stores
entries in an in-process `Map`, which is empty when a new `next start`
process starts. Its first `/en` request misses both `/en` and
`/[locale]`; runtime validation rejects the attempt to regenerate the
empty generic shell and returns HTTP 500.

The build now records whether the fallback HTML shell was empty. On a
miss for an empty shell, `next start` generates the most specific
eligible shell instead of prerendering the generic fallback again. The
first request waits for that render. Nonempty fallbacks still serve
immediately and upgrade in the background, preserving #91231 and its
`partialPrefetching` gate from #96297.

Fixes #98732
parent 0556c918
...@@ -347,6 +347,9 @@ export interface DynamicPrerenderManifestRoute ...@@ -347,6 +347,9 @@ export interface DynamicPrerenderManifestRoute
*/ */
throwOnEmptyStaticShell?: boolean throwOnEmptyStaticShell?: boolean
/** True if the build produced an empty static HTML shell. */
hasEmptyStaticShell?: boolean
/** /**
* When defined, it describes the revalidation configuration for the fallback * When defined, it describes the revalidation configuration for the fallback
* route. * route.
...@@ -3950,6 +3953,8 @@ export default async function build( ...@@ -3950,6 +3953,8 @@ export default async function build(
route.remainingPrerenderableParams, route.remainingPrerenderableParams,
throwOnEmptyStaticShell: throwOnEmptyStaticShell:
prerenderCandidate?.throwOnEmptyStaticShell, prerenderCandidate?.throwOnEmptyStaticShell,
hasEmptyStaticShell:
routeResult?.hasEmptyStaticShell || undefined,
renderingMode: isAppPPREnabled renderingMode: isAppPPREnabled
? isRoutePPREnabled ? isRoutePPREnabled
? RenderingMode.PARTIALLY_STATIC ? RenderingMode.PARTIALLY_STATIC
......
...@@ -1165,6 +1165,7 @@ export function createAppPageEntrypoint({ ...@@ -1165,6 +1165,7 @@ export function createAppPageEntrypoint({
if ( if (
nextConfig.partialPrefetching && nextConfig.partialPrefetching &&
prerenderInfo?.fallback === null && prerenderInfo?.fallback === null &&
!prerenderInfo.hasEmptyStaticShell &&
!hasOmittedConcreteFallbackParam && !hasOmittedConcreteFallbackParam &&
!hasUnresolvedRootFallbackParams && !hasUnresolvedRootFallbackParams &&
remainingPrerenderableParams.length > 0 remainingPrerenderableParams.length > 0
......
export function generateStaticParams() {
return [{ locale: 'en' }, { locale: 'fr' }]
}
export default async function Page({
params,
}: {
params: Promise<{ locale: string }>
}) {
const { locale } = await params
return <h1>Locale: {locale}</h1>
}
import type { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import cheerio from 'cheerio'
import { nextTestSetup } from 'e2e-utils'
describe('cache-components-cold-cache', () => {
const { next } = nextTestSetup({
files: __dirname,
})
it.each(['en', 'fr', 'de'])(
'renders /%s after a cold cache miss',
async (locale) => {
const response = await next.fetch(`/${locale}`)
expect(response.status).toBe(200)
const $ = cheerio.load(await response.text())
expect($('h1').text()).toBe(`Locale: ${locale}`)
expect(next.cliOutput).not.toContain("key: '/[locale]', isFallback: true")
}
)
})
const entries = new Map()
module.exports = class CacheHandler {
async get(key, context) {
const entry = entries.get(key) ?? null
console.log('[cache.get]', {
key,
isFallback: context.isFallback,
hit: entry !== null,
})
return entry
}
async set(key, value) {
entries.set(key, { value, lastModified: Date.now() })
}
async revalidateTag() {
entries.clear()
}
resetRequestCache() {}
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
cacheHandler: require.resolve('./cache-handler.js'),
}
export default nextConfig
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