# There was an error while hydrating

> There was an error while hydrating means React gave up on the server HTML after an earlier error and rendered a Suspense boundary or the whole page again.

Source: https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating
Last updated: 2026-09-18

"There was an error while hydrating" is a follow-up, not the bug itself: React
logs it after another error during hydration, to say it discarded the server
HTML and rendered that part in the browser instead. Error #423 means the whole
page; #422 means one Suspense boundary. Fix the error logged before it.

## The error

React 18, when the failure is outside any `<Suspense>` boundary (#423):

```text
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

React 18, inside a boundary (#422):

```text
Uncaught Error: There was an error while hydrating this Suspense boundary. Switched to client rendering.
```

React 18 also logs this warning in development when the whole root falls
back. The tag is your root container: `<div>` for a `#root` or `#__next`
element, `<#document>` when React hydrates the whole document:

```text
Warning: An error occurred during hydration. The server HTML was replaced with client content in <div>.
```

React 19 reworded both:

```text
There was an error while hydrating but React was able to recover by instead client rendering the entire root.
There was an error while hydrating but React was able to recover by instead client rendering from the nearest Suspense boundary.
```

Production builds print `Minified React error #423` or `#422`. See
[minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423).

## What there was an error while hydrating means

Hydration failed somewhere, and React recovered by rendering part of the page
from scratch in the browser. Which part depends on where the failure was:

| Where it failed                | React 18 | React 19 | What React renders again        |
| ------------------------------ | -------- | -------- | ------------------------------- |
| Outside any `<Suspense>`       | #423     | #423     | The whole root: the entire page |
| Inside a `<Suspense>` boundary | #422     | #422     | Only that boundary              |

The page keeps working, which is why this is a recoverable error. But the
server's work is thrown away, the content may flash, and anything a user typed
before hydration is lost.

The cause differs by version:

- **React 18** logs it after every hydration mismatch, following
  ["Hydration failed because the initial UI does not match"](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
  (#418) or
  ["Text content does not match server-rendered HTML"](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
  (#425). Fix that first error.
- **React 19** logs a mismatch as #418 only. It logs #422 or #423 when a
  component threw an exception while hydrating. The original exception is the
  error's `cause`: expand it in the console.

## Common causes

- **A hydration mismatch** (React 18): a time, a locale-formatted value, a
  `typeof window` branch, invalid nesting. See
  [common causes of hydration errors](https://hydration.jscrate.dev/docs/causes).
- **A component that throws only in the browser**: it reads a property of
  data that the browser does not have yet, or calls an API that fails there.
  See [server and client data](https://hydration.jscrate.dev/docs/causes/data).
- **`useSyncExternalStore` without a server snapshot**, which throws
  ["Missing getServerSnapshot"](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot).

A boundary that React 18 rendered again because it received an update too
early has its own message:
[Suspense boundary received an update before hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating)
(#421).

## How to fix it

1. **Scroll up to the first error.** In React 18, it is the warning and the
   error logged just before this one. In React 19, expand `cause`.
2. **Fix that error** using its page in
   [the list of hydration error messages](https://hydration.jscrate.dev/docs/errors).
3. **Add `<Suspense>` boundaries around independent parts of the page.** A
   failure then costs one boundary (#422) instead of the whole root (#423):

   ```tsx title="app/dashboard/page.tsx"
   import { Suspense } from "react";

   import { ActivityFeed } from "./activity-feed";
   import { Stats } from "./stats";

   export default function Dashboard() {
     return (
       <main>
         <Stats />
         <Suspense fallback={<p>Loading activity…</p>}>
           <ActivityFeed />
         </Suspense>
       </main>
     );
   }
   ```

   A boundary limits the damage. It does not fix the mismatch inside it.

## Find every instance

hydration-proof reports a boundary React rendered again as
[HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) and a root as [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004),
with React's error attached, and the mismatch that started it (for example
[HP1001](https://hydration.jscrate.dev/docs/issues/hp1001)) as its own finding with the source line:

```bash
npx hydration-proof test --mode both
```

A page rendered again from scratch is also reported as
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011), and a single branch as
[HP1010](https://hydration.jscrate.dev/docs/issues/hp1010). The [ESLint rules](https://hydration.jscrate.dev/docs/rules) catch most of
the mismatches that start the chain.

## Related

- [Minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423)
- [Hydration failed because the initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)
- [All minified React hydration codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)