Hydration Proof

Search documentation

Find a page or section

React hydration error messages

hydration-proofv1.0.0View as Markdown

The exact strings React prints, by version, with a page for each.

React hydration error messages tell you that the first browser render did not match the server HTML, or that hydration stopped for another reason. Find the message you saw below. Its page explains the likely causes and what to check next.

Every message, by React version

React 18 and 19 use different wording. Production builds may show a number instead of the full message.

The page rendered different text or elements

  • React 19: Hydration failed because the server rendered HTML didn't match the client. See the React 19 error (production code #418).
  • React 18: Hydration failed because the initial UI does not match what was rendered on the server. See the React 18 error (production code #418).
  • Text only: React 18 says Text content does not match server-rendered HTML. or Text content did not match. Server: … Client: …. React 19 says Hydration failed because the server rendered text didn't match the client. See text mismatches (production code #425 in React 18, #418 in React 19).
  • An element exists on only one side: React 18 says Warning: Expected server HTML to contain a matching <div> in <div>. React 19 shows a + or - element in its diff. See expected server HTML.

Attributes differ, but React keeps the page

  • React 19: A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. See attribute mismatches.
  • React 18: Warning: Prop `className` did not match. Server: … Client: … or Warning: Extra attributes from the server: class,style. See class names and extra attributes. These warnings have no production code.

React could not finish hydrating

  • There was an error while hydrating. is a follow-up message about a root or Suspense boundary that React rendered again. See the recovery message (codes #423 and #422).
  • This Suspense boundary received an update before it finished hydrating. is a React 18 message. See the early-update error (code #421).
  • Missing getServerSnapshot, which is required for server-rendered content. See the external-store error (code #407).

Invalid HTML or a server crash

The production codes have their own pages: minified React error #418, #423, #425, and every hydration code in one table.

Which one am I seeing?

Look at how the message starts:

  • Minified React error #: Open the code list to decode a production error.
  • Hydration failed because: React replaced part of the server HTML. Start with the React 19 or React 18 explanation.
  • Warning:: In React 18, look for the element or prop named in the warning, then choose its page above.
  • A tree hydrated but: React 19 kept the page but found an attribute mismatch.
  • In HTML, or validateDOMNesting: The browser repaired invalid nesting.
  • There was an error while hydrating: This describes recovery. Read the earlier error first.
  • ReferenceError: Check whether a browser global ran on the server.

One bug can produce several messages. Start with the earliest one that names the changed element or value; later messages may describe how React recovered.

To see which wording you get, check the React version your app uses:

npm ls react react-dom   # pnpm why react · yarn why react · bun pm ls

Check the installed React version before using a version-specific explanation.

Find the cause, whatever the message

The message identifies a symptom, not always the cause. Dates, browser-only reads, invalid HTML, and scripts that change the page can all lead to similar errors. See common causes or the React hydration guide.

To check routes beyond the page you have open, run:

npx hydration-proof test --mode both

The report gives each difference an issue code and shows the affected element, both values, and a likely cause.