Hydration Proof

Search documentation

Find a page or section

HP2006: The server could not finish rendering a boundary

hydration-proofv1.0.0View as Markdown

HP2006 (server render error): the server failed to render a Suspense boundary, so the browser had to render it (React error #419). Where to look and the fix.

HP2006 (server-render-error) means the server threw, or gave up, while rendering part of the page inside a Suspense boundary. React sent the fallback instead and rendered that part in the browser (React error #419). The problem is on the server, not in hydration: check the server logs for the error it threw while rendering that boundary.

CodeHP2006
Nameserver-render-error
Default severityError
GroupProblems React reported
What it meansThe server failed to render part of the page and the client had to render it (React error 419).

What HP2006 (server-render-error) means

With streaming server rendering, an error inside a Suspense boundary does not fail the whole response. React streams the boundary's fallback, and when the page loads, the browser renders that boundary from scratch. Until it does, users see the fallback where the content should be, and the browser does the work the server should have done.

In a development build, React tells the browser why. In production the reason stays on the server, and the browser only gets error #419.

The React error it matches

The server could not finish this Suspense boundary, likely due to an error during server rendering. Switched to client rendering.
Switched to client rendering because the server rendering errored:
Minified React error #419

The development message quotes the server's error after the colon, and it says "aborted" instead of "errored" when the server stopped rendering, for example after a timeout. See the minified React error codes for #419.

Likely causes

  • A data request that fails on the server: an API that is unreachable from the test environment, a missing environment variable or credentials.
  • Code that only works in the browser, such as a read of window, inside a component the server renders: window is not defined.
  • A server render that is aborted before a slow boundary finishes.

How to fix it

  • Check the server logs: the server threw while rendering this Suspense boundary.
  1. When hydration-proof started the app, the HTML report lists the error and warning lines the server printed while the page loaded. With --url, check the logs of the server you started.
  2. Run npx hydration-proof test --mode dev to get the server's error message in the browser.
  3. Fix the error, or make the component handle it (a guard, an error boundary) so the server can finish the boundary. If the test environment lacks data, an API or a secret the server needs, seed it with hooks.setup or add it to the server's environment.

Example

  ✖ /reports 2.1s  1 error
    HP2006 The server could not finish rendering a boundary
      Minified React error #419; visit https://react.dev/errors/419 for the full message or use the non-minified dev environment for full errors and additional helpful warnings. (React error #419)
      → Check the server logs: the server threw while rendering this Suspense boundary.