HP2001 (react-hydration-error) means React reported that hydration failed,
for example with minified error #418, but hydration-proof's DOM comparison
could not tie the failure to a specific element. Run the test in development
mode: React's full message, its component stack and the source lines point to
the difference.
| Code | HP2001 |
|---|---|
| Name | react-hydration-error |
| Default severity | Error |
| Group | Problems React reported |
| What it means | React reported that hydration failed. The DOM comparison could not locate the exact difference. |
What HP2001 (react-hydration-error) means
hydration-proof records React's own errors and warnings, in development and production builds of React 18 and 19. Most of the time the DOM comparison finds the difference that made React fail, and React's message is attached to that finding as evidence: a text mismatch is reported as HP1001, not HP2001.
HP2001 is what is left when React reported a failure in a hydration commit and no DOM finding from that commit explains it. The finding carries React's message and, when React provides one, the component stack.
The React error it matches
These are the messages that become HP2001 when nothing else explains them:
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Hydration failed because the initial UI does not match what was rendered on the server.
Text content does not match server-rendered HTML.
Minified React error #418; visit https://react.dev/errors/418The first is React 19, the next two React 18. Production builds show only a number: #418, or #425 for React 18's text message. Each has its own page: the server rendered HTML didn't match the client, the initial UI does not match, text content does not match and minified React error #418.
Likely causes
React's message is generic, so the cause has to be found from the component:
the usual suspects are a time-dependent value, a
browser-only API branch,
browser storage and
invalid HTML nesting. The difference may also sit
in an element hydration-proof does not compare, such as a subtree you excluded
with ignore.selectors.
How to fix it
- Run hydration-proof in development mode (
--mode dev) for React's detailed diff.
Start with the development build of the same route:
npx hydration-proof test --mode dev --route /checkoutReact 19's development message ends with a diff of the server and client
markup (+ for the client, - for the server), and development builds give
hydration-proof the component names and source lines it needs. Then:
- If the finding becomes a DOM code (HP1001, HP1007…) in development, follow that code's page.
- If it only happens in production, test both modes with
--mode both: issues found in only one mode are marked. See errors that only happen in production.
Example
✖ /checkout 1.4s 1 error
HP2001 React reported a hydration error
Minified React error #418; visit https://react.dev/errors/418?args[]=HTML&args[]= for the full message or use the non-minified dev environment for full errors and additional helpful warnings. (React error #418)
→ Run hydration-proof in development mode (--mode dev) for React's detailed diff.Production builds minify component names, so this finding shows none; the development run adds component names and source lines.