HP2002 (react-hydration-warning) means React logged a hydration mismatch
warning in a development build, and no difference hydration-proof found in the same
hydration commit explains it. Read React's message: it names the element or
prop that differs, and often both values. Then fix the difference like any
other mismatch.
| Code | HP2002 |
|---|---|
| Name | react-hydration-warning |
| Default severity | Warning |
| Group | Problems React reported |
| What it means | React logged a hydration mismatch warning (development builds only). |
What HP2002 (react-hydration-warning) means
In development, React logs a warning for many mismatches it can recover from
or does not fix: attributes, extra attributes, text, and elements it expected
or did not expect. hydration-proof reads each warning. When a DOM finding from
the same hydration commit explains it, the warning is attached to that finding
as evidence (a className warning to HP1004, for
example). HP2002 is a warning nothing else explains.
Production builds do not log these warnings, so HP2002 only appears in
development runs (--mode dev or --mode both). When React 18 quotes the
values, as in "Prop title did not match. Server: … Client: …", the finding
carries the prop name and both values.
The React error it matches
The development warnings that become HP2002:
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Text content did not match. Server: "5 minutes ago" Client: "6 minutes ago"
Warning: Prop `className` did not match. Server: "theme-light" Client: "theme-dark"
Warning: Expected server HTML to contain a matching <div> in <div>
Warning: Did not expect server HTML to contain a <div> in <div>
Warning: Extra attributes from the server: data-rendered-on
An error occurred during hydration. The server HTML was replaced with client content in <div>The first is React 19, the rest React 18. Nesting warnings, such as
"In HTML, <div> cannot be a descendant of <p>", are reported as
HP3001 instead. Each message has a page under
React hydration error messages, for example
attributes didn't match
and Expected server HTML to contain a matching.
Likely causes
The warning says what differs; the reason is one of the usual causes of hydration errors: a theme class, a time or locale value, or a browser-only API branch.
How to fix it
- Find the element from React's message and the component stack attached to the finding (open it in the HTML report).
- Look up the error message's page for what it means, and the cause page for the fix.
- If the difference is inside an element you excluded with
ignore.selectors, hydration-proof does not compare it; React still does. Fix it, or ignore HP2002 for that route with a reason (see ignoring findings).