fix(app-router): recover SSR shell render errors via __next_error__ document #1908
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,7 +18,7 @@ import { | |
| setServerCallback, | ||
| } from "@vitejs/plugin-rsc/browser"; | ||
| import { flushSync } from "react-dom"; | ||
| import { createRoot, hydrateRoot } from "react-dom/client"; | ||
| import "../client/instrumentation-client.js"; | ||
| import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js"; | ||
| import { | ||
|
|
@@ -1603,16 +1603,34 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void { | |
| onCaughtError: prodOnCaughtError, | ||
| onUncaughtError, | ||
| }); | ||
| const children = createElement(BrowserRoot, { | ||
| initialElements: root, | ||
| initialNavigationSnapshot, | ||
| }); | ||
| // The `__next_error__` marker is intentionally broad: it detects the default | ||
| // error document generally, not only the new SSR shell-error recovery path. | ||
| // Both `DefaultGlobalError` (used here) and the boundary renderer emit | ||
| // `<html id="__next_error__">`, so this branch also fires for legacy server- | ||
| // rendered global-error pages. That is upstream-compatible — the browser | ||
| // should always createRoot when the document is the default error shell. | ||
| if (document.documentElement.id === "__next_error__") { | ||
|
Contributor
There was a problem hiding this comment. Behavior-change worth confirming: on This is plausibly upstream-compatible (Next.js client-renders the recovery shell), and the embedded flight payload encodes the same error tree so the rendered content matches. But the new browser spec only exercises the SSR-only-throw recovery path, not the legacy server-digest-error path through this same branch. Worth a quick confirmation (or a test) that a genuine server-side digest error with no custom global-error still renders the default error card correctly via |
||
| for (const style of document.querySelectorAll("style[data-vinext-error-shell-style]")) { | ||
| style.remove(); | ||
| } | ||
| startTransition(() => { | ||
| const clientRoot = createRoot(document, hydrateRootOptions); | ||
|
Contributor
There was a problem hiding this comment.
|
||
| clientRoot.render(children); | ||
| window.__VINEXT_RSC_ROOT__ = clientRoot; | ||
| }); | ||
| } else { | ||
| window.__VINEXT_RSC_ROOT__ = hydrateRootInTransition({ | ||
| children, | ||
| container: document, | ||
| hydrateRoot, | ||
| options: hydrateRootOptions, | ||
| startTransition, | ||
| }); | ||
| } | ||
|
|
||
| const navigateRsc: NavigationRuntimeNavigate = async function navigateRsc( | ||
| href: string, | ||
|
|
@@ -2190,6 +2208,11 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void { | |
| // original document from there, so let the next HMR update reload the | ||
| // current URL. If the edit fixed the error the page comes back clean; if | ||
| // not, initial dev server errors re-populate the overlay. | ||
| // | ||
| // The `__next_error__` marker is broad — see the matching comment in | ||
| // bootstrapHydration above. Reloading here is safe for any default-error | ||
| // document because the dev server will render the current state of the | ||
| // source after the edit. | ||
| if (document.documentElement.id === "__next_error__") { | ||
| window.location.reload(); | ||
| return; | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -267,6 +267,11 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = { | |
| probeLayoutAt: (layoutIndex: number, layoutParamAccess?: AppLayoutParamAccessTracker) => unknown; | ||
| probePage: () => unknown; | ||
| expireSeconds?: number; | ||
| /** True when the app supplies a custom global-error.tsx (generated entry | ||
| * knows this at build time). Gates SSR shell-error recovery: without a | ||
| * custom global-error, shell errors serve the default `__next_error__` | ||
| * recovery document instead of a server-side boundary re-render. */ | ||
| hasCustomGlobalError?: boolean; | ||
| renderErrorBoundaryPage: (error: unknown) => Promise<Response | null>; | ||
| renderHttpAccessFallbackPage: ( | ||
| statusCode: number, | ||
|
|
@@ -979,6 +984,7 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>( | |
| return renderPageSpecialError(options, specialError); | ||
| }, | ||
| renderToReadableStream: options.renderToReadableStream, | ||
| hasCustomGlobalError: options.hasCustomGlobalError, | ||
|
Contributor
There was a problem hiding this comment. This threads the flag into the initial render lifecycle. The background-revalidation |
||
| routePattern: route.pattern, | ||
| runWithSuppressedHookWarning(probe) { | ||
| return options.runWithSuppressedHookWarning(probe); | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -170,6 +170,10 @@ type RenderAppPageLifecycleOptions = { | |
| element: ReactNode | AppOutgoingElements, | ||
| options: { onError: AppPageBoundaryOnError }, | ||
| ) => ReadableStream<Uint8Array>; | ||
| /** True when the app supplies a custom global-error.tsx. When false, SSR | ||
| * shell render errors fall back to the default `__next_error__` recovery | ||
| * document instead of a server-side boundary re-render. */ | ||
| hasCustomGlobalError?: boolean; | ||
| routePattern: string; | ||
| runWithSuppressedHookWarning<T>(probe: () => Promise<T>): Promise<T>; | ||
| scriptNonce?: string; | ||
|
|
@@ -836,6 +840,7 @@ export async function renderAppPageLifecycle( | |
| rscStream: rscForResponse, | ||
| scriptNonce: options.scriptNonce, | ||
| sideStream: rscCapture.sideStream, | ||
| hasCustomGlobalError: options.hasCustomGlobalError, | ||
| ssrHandler, | ||
| waitForAllReady: options.isPrerender, | ||
| }); | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -132,6 +132,10 @@ export type AppPageSsrHandler = { | |
| waitForAllReady?: boolean; | ||
| /** Dev-only: original server error to surface in the browser overlay. */ | ||
| initialDevServerError?: unknown; | ||
| /** When true, an SSR-phase-only shell render error resolves to the | ||
| * default `__next_error__` error-document shell (with the original | ||
| * flight payload and bootstrap) instead of rejecting. See handleSsr. */ | ||
| fallbackToErrorDocumentOnShellError?: boolean; | ||
| }, | ||
| ) => Promise<ReadableStream<Uint8Array> | AppSsrRenderResult>; | ||
| }; | ||
|
|
@@ -166,6 +170,10 @@ type RenderAppPageHtmlStreamOptions = { | |
| waitForAllReady?: boolean; | ||
| /** Dev-only: original server error to surface in the browser overlay. */ | ||
| initialDevServerError?: unknown; | ||
| /** True when the app supplies a custom global-error.tsx. Disables the | ||
| * default error-document shell fallback so SSR shell errors keep driving | ||
| * the server-rendered global-error boundary re-render. */ | ||
| hasCustomGlobalError?: boolean; | ||
| }; | ||
|
|
||
| type RenderAppPageHtmlResponseOptions = { | ||
|
|
@@ -227,6 +235,9 @@ export async function renderAppPageHtmlStream( | |
| capturedRscDataRef: options.capturedRscDataRef, | ||
| waitForAllReady: options.waitForAllReady, | ||
| initialDevServerError: options.initialDevServerError, | ||
| // Only when the caller affirmatively knows there is no custom | ||
| // global-error.tsx; undefined (unknown) keeps reject semantics. | ||
| fallbackToErrorDocumentOnShellError: options.hasCustomGlobalError === false, | ||
| }; | ||
|
|
||
| const rawResult = await options.ssrHandler.handleSsr( | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -48,6 +48,7 @@ import { BfcacheStateKeyMapContext, ElementsContext, Slot } from "vinext/shims/s | |
| import { AppRouterContext } from "vinext/shims/internal/app-router-context"; | ||
| import { createClientReferencePreloader } from "./app-client-reference-preloader.js"; | ||
| import { RSC_FORM_STATE_GLOBAL } from "./app-browser-hydration.js"; | ||
| import DefaultGlobalError from "vinext/shims/default-global-error"; | ||
|
|
||
| /** | ||
| * `@types/react-dom` does not yet type `maxHeadersLength` (it pairs with the | ||
|
|
@@ -106,6 +107,58 @@ function getErrorMessage(error: unknown): string { | |
| return Object.prototype.toString.call(error); | ||
| } | ||
|
|
||
| function createUtf8Stream(html: string): ReadableStream<Uint8Array> { | ||
| const encoder = new TextEncoder(); | ||
| return new ReadableStream<Uint8Array>({ | ||
| start(controller) { | ||
| controller.enqueue(encoder.encode(html)); | ||
| controller.close(); | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| function buildBootstrapModuleScript(bootstrapModuleUrl?: string, nonce?: string): string { | ||
| if (!bootstrapModuleUrl) return ""; | ||
| return ( | ||
| `<script type="module"${createNonceAttribute(nonce)} src="` + | ||
| escapeHtmlAttr(bootstrapModuleUrl) + | ||
| '" id="_R_" async=""></script>' | ||
| ); | ||
| } | ||
|
|
||
| function markErrorShellStyle(html: string): string { | ||
| // DefaultGlobalError intentionally emits one style tag. If that changes, | ||
| // update this marker logic without touching styles inserted later by the | ||
| // stream transforms. | ||
| return html.replace("<style>", '<style data-vinext-error-shell-style="">'); | ||
|
Contributor
There was a problem hiding this comment.
|
||
| } | ||
|
|
||
| function renderSsrErrorDocumentShell( | ||
| bootstrapModuleUrl?: string, | ||
| nonce?: string, | ||
| ): ReadableStream<Uint8Array> { | ||
| const html = markErrorShellStyle( | ||
| renderToStaticMarkup( | ||
| createReactElement(DefaultGlobalError, { | ||
| error: null, | ||
| }), | ||
| ), | ||
| ); | ||
| const bootstrapScript = buildBootstrapModuleScript(bootstrapModuleUrl, nonce); | ||
| if (!bootstrapScript) { | ||
| return createUtf8Stream(`<!DOCTYPE html>${html}`); | ||
| } | ||
|
|
||
| const documentClose = "</body></html>"; | ||
| if (!html.endsWith(documentClose)) { | ||
| return createUtf8Stream(`<!DOCTYPE html>${html}${bootstrapScript}`); | ||
| } | ||
|
|
||
| return createUtf8Stream( | ||
| `<!DOCTYPE html>${html.slice(0, -documentClose.length)}${bootstrapScript}${documentClose}`, | ||
| ); | ||
| } | ||
|
|
||
| function renderInsertedHtml(insertedElements: readonly unknown[]): string { | ||
| let insertedHTML = ""; | ||
|
|
||
|
|
@@ -306,6 +359,12 @@ export async function handleSsr( | |
| * to resolve before returning the HTML stream. Used for static prerender | ||
| * and ISR cache writes to avoid caching fallback content. */ | ||
| waitForAllReady?: boolean; | ||
| /** When true, an SSR-phase shell render error (no RSC-originated `digest`) | ||
| * resolves to the default `__next_error__` error-document shell with the | ||
| * original flight payload and bootstrap module, instead of rejecting. | ||
| * Callers set this only when the app has no custom global-error.tsx, so | ||
| * boundary re-render semantics are unaffected. */ | ||
| fallbackToErrorDocumentOnShellError?: boolean; | ||
| }, | ||
| ): Promise<AppSsrRenderResult> { | ||
| return runWithNavigationContext(async () => { | ||
|
|
@@ -501,8 +560,6 @@ export async function handleSsr( | |
| }, | ||
| }; | ||
|
|
||
| // Populated before any SSR request runs: at prod-server startup | ||
| // (prod-server.ts) or via build-time bundle injection (index.ts). Left | ||
| // undefined in dev, which naturally disables inline CSS there. | ||
|
|
@@ -560,8 +617,36 @@ export async function handleSsr( | |
| const getBeforeInteractiveHeadHTML = (): string => | ||
| renderBeforeInteractiveInlineScripts(beforeInteractiveInlineScripts); | ||
|
|
||
| let renderedHtmlStream: Awaited<ReturnType<typeof renderToReadableStream>> | undefined; | ||
| let htmlStream: ReadableStream<Uint8Array>; | ||
| try { | ||
| renderedHtmlStream = await renderToReadableStream(ssrRoot, ssrRenderOptions); | ||
| if (options?.waitForAllReady === true) { | ||
| await renderedHtmlStream.allReady; | ||
| } | ||
| htmlStream = renderedHtmlStream; | ||
|
Contributor
There was a problem hiding this comment. On the |
||
| } catch (error) { | ||
| void renderedHtmlStream?.cancel().catch(() => {}); | ||
| // Contract with renderAppPageHtmlStreamWithRecovery (app-page-stream.ts): | ||
| // a rejected handleSsr drives redirect()/notFound() responses and | ||
| // local/global error.tsx boundary re-renders. Errors that originate in | ||
| // the RSC render (rethrown here through the flight deserializer) carry | ||
| // a string `digest` and must always propagate so those semantics stay | ||
| // intact. Only an SSR-phase-only shell error — and only when the app | ||
| // has no custom global-error.tsx (the caller sets the flag) — falls | ||
| // back to the default `__next_error__` document shell: the original | ||
| // flight payload plus the bootstrap module are still emitted, so the | ||
| // browser recovers by re-rendering the real tree from the embedded | ||
| // RSC data (Next.js shell-error recovery semantics). This resolves | ||
| // as a successful shell render, so the caller preserves its normal | ||
| // status and ISR eligibility rather than treating it as a 500. | ||
| if ( | ||
| options?.fallbackToErrorDocumentOnShellError !== true || | ||
| typeof (error as { digest?: unknown } | null)?.digest === "string" | ||
| ) { | ||
| throw error; | ||
| } | ||
| htmlStream = renderSsrErrorDocumentShell(bootstrapModuleUrl, options?.scriptNonce); | ||
| } | ||
|
|
||
| const finalStream = deferUntilStreamConsumed( | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -19,3 +19,12 @@ export function stripViteModuleQuery(id: string): string { | |
| const queryIndex = id.search(/[?#]/); | ||
| return queryIndex === -1 ? id : id.slice(0, queryIndex); | ||
| } | ||
|
|
||
| /** Strip a trailing `.js` extension from a module specifier so | ||
| * `resolveShimModulePath` looks for the correct base name (e.g. `headers.js` | ||
| * → `headers`). Public and internal shim imports may carry extensionful | ||
| * subpaths; normalising before resolution prevents looking for non-existent | ||
| * files like `headers.js.ts`. */ | ||
| export function stripJsExtension(name: string): string { | ||
| return name.endsWith(".js") ? name.slice(0, -3) : name; | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Boolean(${globalErrorVar}?.default)correctly treats aglobal-errorfile with no default export as "no custom global error" — so an app with a malformedglobal-error.tsx(file present, no default) would still get the__next_error__recovery shell rather than the server-side boundary path. That's a reasonable choice, but worth confirming it matches Next.js, which I believe validates/throws on aglobal-errorwithout a default export rather than silently falling back. Non-blocking, but a candidate for a follow-up parity check.