# HP2002: React warned about a hydration mismatch

> HP2002 (React hydration warning): React logged a hydration mismatch warning in a development build that no DOM finding explains. What it means and what to do.

Source: https://hydration.jscrate.dev/docs/issues/hp2002
Last updated: 2026-09-18

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](https://hydration.jscrate.dev/docs/issues/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:

```text
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](https://hydration.jscrate.dev/docs/issues/hp3001) instead. Each message has a page under
[React hydration error messages](https://hydration.jscrate.dev/docs/errors), for example
[attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
and [Expected server HTML to contain a matching](https://hydration.jscrate.dev/docs/errors/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](https://hydration.jscrate.dev/docs/causes): a
[theme](https://hydration.jscrate.dev/docs/causes/theme) class, a [time](https://hydration.jscrate.dev/docs/causes/time) or
[locale](https://hydration.jscrate.dev/docs/causes/locale) value, or a
[browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch.

## How to fix it

1. Find the element from React's message and the component stack attached to
   the finding (open it in the HTML report).
2. Look up the error message's page for what it means, and the cause page for
   the fix.
3. 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](https://hydration.jscrate.dev/docs/ignoring)).

## Related

- [HP2001: React reported a hydration error](https://hydration.jscrate.dev/docs/issues/hp2001)
- [HP2007: an uncaught error while loading](https://hydration.jscrate.dev/docs/issues/hp2007)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)