# HP2001: React reported a hydration error

> HP2001 (React hydration error): React said hydration failed, but the DOM comparison could not locate the difference. How to find it, and what #418 means.

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

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

```text
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/418
```

The first is React 19, the next two React 18. Production builds show only a
number: #418, or [#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425) for React 18's
text message. Each has its own page:
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client),
[the initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match),
[text content does not match](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
and [minified React error #418](https://hydration.jscrate.dev/docs/errors/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](https://hydration.jscrate.dev/docs/causes/time), a
[browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch,
[browser storage](https://hydration.jscrate.dev/docs/causes/storage) and
[invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html). 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:

```bash
npx hydration-proof test --mode dev --route /checkout
```

React 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:

1. If the finding becomes a DOM code (HP1001, HP1007…) in development, follow
   that code's page.
2. 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](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## Example

```text
  ✖ /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.

## Related

- [HP2002: React warned about a mismatch](https://hydration.jscrate.dev/docs/issues/hp2002)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)