Hydration Proof

Search documentation

Find a page or section

HP2003: A Suspense boundary switched to client rendering

hydration-proofv1.0.0View as Markdown

HP2003 (boundary client rendered): React could not hydrate a Suspense boundary and rendered it on the client instead (React error #422). What to check first.

HP2003 (boundary-client-rendered) means React could not hydrate a Suspense boundary and rendered its content on the client instead, throwing the server HTML inside it away. The rest of the page hydrated normally. Check the error React reported for the boundary: until it is fixed, the boundary is rendered on the client on every load.

CodeHP2003
Nameboundary-client-rendered
Default severityError
GroupProblems React reported
What it meansReact could not hydrate a Suspense boundary and rendered it on the client instead.

What HP2003 (boundary-client-rendered) means

When hydration fails inside a Suspense boundary, React recovers there: it discards the boundary's server HTML and renders it from scratch, and logs why. hydration-proof compares each boundary's hydration commit on its own, so it usually also sees the difference React hit and reports that (a DOM code such as HP1001, or HP1010 for the replaced branch), with React's message as evidence.

HP2003 stands alone when React reported the switch and no DOM finding from that commit explains it, for example because the difference is inside a subtree excluded with ignore.selectors. When React attaches the original error, the finding shows it after "Caused by:".

The React error it matches

There was an error while hydrating this Suspense boundary. Switched to client rendering.

This is React 18's message; production builds show minified error #422. See there was an error while hydrating. If the failure is outside every boundary, the whole root switches instead: HP2004.

Likely causes

How to fix it

  • Check the error React reported for this boundary; the boundary is rendered on the client until it is fixed.
  1. Open the finding in the HTML report. Its evidence has React's message, the underlying error when there is one, and the component stack.
  2. Run npx hydration-proof test --mode dev for readable component names and source lines.
  3. Fix the difference React found, using the page of the matching DOM code or cause, and run the test again.

Example

  ✖ /dashboard 1.5s  1 error
    HP2003 A Suspense boundary switched to client rendering
      in UsageChart
      There was an error while hydrating this Suspense boundary. Switched to client rendering.
      → Check the error React reported for this boundary; the boundary is rendered on the client until it is fixed.