Hydration Proof

Search documentation

Find a page or section

HP1010: React discarded server HTML and rendered a branch again

hydration-proofv1.0.0View as Markdown

HP1010 (branch replaced): hydration failed inside a branch, so React threw its server HTML away and rendered it on the client. Why it costs you, and the fix.

HP1010 (branch-replaced) means hydration failed inside part of the page, so React threw away that branch's server HTML and rendered it again on the client. That costs a second render, resets the state inside the branch, and happens on every page load until the mismatch is fixed. Find the mismatch in that branch and fix it.

CodeHP1010
Namebranch-replaced
Default severityError
GroupDOM mismatches
What it meansHydration failed inside this branch, so React threw away the server HTML and rendered it on the client. This costs performance and resets state.

What HP1010 (branch-replaced) means

When React finds a difference it cannot hydrate, it gives up on the nearest Suspense boundary: it discards the server HTML inside it and renders that part from scratch. Everything in the branch is created again, so inputs come back empty and an element that had focus loses it (HP5002 and HP5003 check both).

hydration-proof sees this by giving every node an identity: it knows which server nodes React reused and which it replaced. In most cases it also finds the concrete difference inside the branch, and then reports that instead (a text, element or attribute code) with "React discarded the server HTML of <section> and rendered it again on the client" as evidence. HP1010 appears on its own when React replaced a branch but the exact difference inside it could not be located.

If the replaced part is the whole root rather than a branch, the code is HP1011.

The React error it matches

React's own report is attached to the finding as evidence:

Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
There was an error while hydrating this Suspense boundary. Switched to client rendering.

The first is React 19, the second React 18. In production they arrive as minified errors, such as #418. See the server rendered HTML didn't match the client and there was an error while hydrating. When React reports this with no DOM change to go with it, the code is HP2003.

Likely causes

Any mismatch can make React replace a branch. The common ones are a time-dependent value, a browser-only API branch, browser storage and invalid HTML nesting. The full list is on common causes of hydration errors.

How to fix it

  • Fix the mismatch inside this branch; React re-renders it on every page load until then.
  1. Read the finding's evidence in the HTML report: React's error and the component stack point into the branch.
  2. Run npx hydration-proof test --mode dev for component names, exact source lines and React's full message instead of a minified code.
  3. Fix the difference React found, using the cause page it points to, and run the test again: the branch is then hydrated instead of replaced.

Example

  ✖ /products/42 1.6s  1 error
    HP1010 React discarded server HTML and rendered a branch again
      #reviews  in Reviews
      React discarded the server HTML of <section> and rendered it again on the client.
      → Fix the mismatch inside this branch; React re-renders it on every page load until then.