HP1011: React discarded the whole server-rendered page

HP1011 (root-replaced) means hydration failed outside any Suspense boundary, so React discarded the server HTML of the entire root and rendered the page again on the client, losing anything the user did before hydration. Fix the mismatch, or wrap the unstable part in a Suspense boundary so only that part is re-rendered.

What HP1011 (root-replaced) means

React recovers from a hydration failure at the nearest Suspense boundary above it. With no boundary in between, that is the root: every element on the page is created again, the server HTML is only a placeholder, and all state is reset.

Like HP1010, this code appears on its own only when hydration-proof saw the replacement but could not locate the concrete difference. When it finds the difference, it reports that instead, with "React discarded the server HTML of the whole root" as evidence.

The React error it matches

React's own report is attached as evidence:

Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

The first is React 19, the second React 18, minified in production as #423. See there was an error while hydrating. When React reports this without a DOM change to go with it, the code is HP2004.

Likely causes

The same mismatches as anywhere else, most often a time-dependent value, browser storage, a theme or invalid HTML in a layout shared by every page. See all causes.

How to fix it

• Fix the mismatch or wrap the unstable part in a Suspense boundary so React only re-renders that part.

Fixing the mismatch is the real fix; see HP1010 for the steps. A Suspense boundary limits the damage while you do, or around a part that will always be unstable:

import { Suspense } from "react";
 
import { Article } from "./article";
import { LastSeen } from "./last-seen";
 
export default function Page() {
  return (
    <main>
      <Suspense fallback={null}>
        <LastSeen />
      </Suspense>
      <Article />
    </main>
  );
}

If LastSeen fails to hydrate now, React re-renders only that boundary and keeps the rest of the server HTML. The finding becomes an HP1010 for the boundary instead of an HP1011 for the page.

Example

  ✖ / 1.2s  1 error
    HP1011 React discarded the whole server-rendered page
      main  in RootLayout
      React discarded the server HTML of the whole root (from <main>) and rendered it again on the client.
      → Fix the mismatch or wrap the unstable part in a Suspense boundary so React only re-renders that part.

Related

• HP1010: React re-rendered one branch
• HP2004: the root switched to client rendering
• Minified React error #423
• Do hydration errors hurt SEO and performance?
• Debugging hydration errors