Skip to content

Hydration errors and SEO: what crawlers get on a mismatch

Hydration error SEO explained: which version of a React or Next.js page non-rendering and rendering crawlers read after a mismatch, and how to diff the two.

By Crawlito · 8 min read

In short

  • A crawler that does not run JavaScript reads the server-rendered HTML, so after a hydration mismatch it keeps the server version of the page.
  • React 19's error says the mismatched tree will be regenerated on the client, so a rendering crawler such as Googlebot can end up with the client version instead.
  • React documents that attribute differences are not guaranteed to be patched and that suppressHydrationWarning leaves mismatched text unpatched, so the server value can survive in the live DOM.
  • The documented causes are typeof window branches, browser-only APIs, Date and locale formatting, changing external data, invalid HTML nesting, browser extensions and edge tools that rewrite HTML.
  • Diff the raw HTML against the hydrated DOM for the title, H1, main text, links and metadata to see whether two kinds of crawler are reading two different pages.
On this page

A hydration error does not hide your page from crawlers, but it can mean different crawlers read different versions of it. A crawler that does not run JavaScript reads the HTML your server sent and never sees the mismatch. A crawler that renders, such as Googlebot, runs React, and when React recovers by re-rendering on the client, it ends up with the client version. The SEO risk is not the console error itself: it is the gap between those two versions when it touches text, links or metadata that matter.

This post covers what React does on a mismatch, which version each kind of crawler reads for each documented cause, and how to diff server HTML against the hydrated DOM. For the general difference between the two documents, start with raw HTML vs rendered HTML.

What React does when server and client output differ

Hydration is the step where React attaches to HTML that was rendered on the server. The hydrateRoot reference says the tree you pass in must produce the same output as it did on the server, and that you should treat mismatches as bugs. Three documented behaviors decide what ends up in the page:

  • React re-renders the mismatched tree on the client. The hydration error message shown in the React 19 release post reads: "Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client." After that, the live DOM holds the client output.
  • Attribute differences may stay. The same reference says there are no guarantees that attribute differences will be patched up, for performance reasons. An href, class or content attribute that differs can keep its server value in the live DOM.
  • Suppressed text is not patched. With suppressHydrationWarning={true}, React does not attempt to patch mismatched text content. The server text stays on screen until your code changes it.

React also says that in the best case a recovered mismatch is a slowdown, and in the worst case event handlers can get attached to the wrong elements. That is a user problem as much as a crawler one.

Which version each kind of crawler reads

There are two kinds of reader to plan for:

ReaderRuns JavaScriptReads after a mismatch
Non-rendering crawlers: the major AI crawlers in public measurements so far, and any HTTP client such as curlNoThe server HTML, exactly as sent
Rendering crawlers: Googlebot, after its render queueYesThe DOM after hydration and any client re-render
A person in a browserYesSame as a rendering crawler, plus effects of their extensions, locale and storage

Google documents that Googlebot renders pages with an evergreen Chromium and uses the rendered HTML to index the page. Most AI crawlers did not execute JavaScript in the public measurements available; do AI crawlers run JavaScript? covers the evidence and its limits. So a mismatch splits your audience: Google can index one version while AI crawlers read another.

The documented causes, and what each crawler sees

The Next.js hydration error page and the React 19 error message list the same family of causes. The question for each is what the server branch contains, because that is all a non-rendering crawler gets.

CauseServer HTML (non-rendering crawler)After hydration (rendering crawler)
typeof window !== 'undefined' branchThe server branchThe client branch
Browser-only APIs (window, localStorage, matchMedia) in renderA default value, or a crash on the serverThe value in that browser
Date(), Date.now(), Math.random()The value at render time on the serverThe value at hydration time
Date formatting in the user's localeThe server's locale and time zoneThe browser's locale and time zone
External data that changed, with no snapshot sentThe data the server fetchedThe data the client fetched
Invalid HTML nesting, such as <div> inside <p>Markup the HTML parser restructuresReact's client tree
Browser extensions, iOS format detectionUnaffectedUnaffected for crawlers; differs only for some visitors
Edge or CDN tools that rewrite the HTMLThe rewritten HTMLClient tree, after a mismatch

Window checks and browser-only APIs

This is the cause most likely to hide content. A component like this sends a placeholder to every crawler that reads raw HTML:

jsx
export function Pricing({ plans }) {
  if (typeof window === "undefined") return <p>Loading plans…</p>;
  return <PlanTable plans={plans} />;
}

Googlebot may index the plan table after rendering, while a non-rendering crawler reads "Loading plans…". The same happens when the server renders a default because it cannot read localStorage or matchMedia, for example a "mobile" layout that leaves out a desktop-only specification table.

Dates, random values and locales

A server in one time zone and a browser in another produce different strings for the same date. The text differs but is usually present in both, so the risk is smaller: an article date or opening hours that read differently to different crawlers. Google says Googlebot's default crawling IP addresses appear to be based in the USA and that it sends requests without an Accept-Language header (locale-adaptive pages). The time zone its renderer uses is not documented, so do not rely on it matching your users. Format dates on the server with an explicit time zone and pass the formatted string down, or render a machine-readable <time datetime="..."> with server text.

Invalid HTML nesting

The HTML parser closes an open paragraph when it meets a block such as a <div> or <ul>: the HTML parsing rules close the <p> before inserting either one, and turn a stray </p> into a new, empty paragraph. So <p><div>Spec</div></p> becomes <p></p><div>Spec</div><p></p> before React runs, the DOM no longer matches React's tree, and React re-renders. The text usually survives in both versions, but the structure differs: a heading or list can sit outside the element you expected. Next.js also lists nested interactive elements, such as an <a> inside an <a>, which affects links. Fix these at the source; they are plain markup bugs.

Extensions and edge rewrites

Browser extensions and iOS phone number detection change the DOM in a visitor's browser, so they do not change what a crawler fetches. React 19 skips unexpected tags in <head> and <body> that third-party scripts and extensions insert, so those insertions no longer trigger a mismatch. An edge tool that rewrites the HTML response is different: Next.js lists an incorrectly configured CDN that modifies HTML as a cause, and that rewrite reaches every crawler, so check the response at the edge, not only at your origin.

How to diff server HTML against the hydrated DOM

The development console tells you that a mismatch happened; React 19 logs one error with a diff. To see what each crawler gets, compare the specific parts that carry meaning.

In the browser console

Run this on a production build of the page. It fetches the raw HTML again, parses it without running scripts, and compares a list of elements with the live DOM:

js
const raw = await (await fetch(location.href, { cache: "no-store" })).text();
const server = new DOMParser().parseFromString(raw, "text/html");
const checks = {
  title: (d) => d.title,
  h1: (d) => d.querySelector("h1")?.textContent.trim(),
  description: (d) => d.querySelector('meta[name="description"]')?.content,
  canonical: (d) => d.querySelector('link[rel="canonical"]')?.href,
  robots: (d) => d.querySelector('meta[name="robots"]')?.content,
  mainWords: (d) => (d.querySelector("main")?.textContent.match(/\S+/g) || []).length,
  links: (d) => d.querySelectorAll("a[href]").length,
};
console.table(Object.fromEntries(
  Object.entries(checks).map(([k, f]) => [k, { server: f(server), hydrated: f(document) }])
));

Any row where the two columns differ is a place where non-rendering and rendering crawlers read different things. The fetch uses your cookies and user agent, so a personalized session can differ from what a crawler gets.

From the command line

To keep evidence, save both versions and diff their text:

bash
curl -sL --compressed https://example.com/pricing -o server.html
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless --dump-dom https://example.com/pricing > hydrated.html

strip() { perl -0pe 's/<script\b.*?<\/script>//gis; s/<[^>]+>/\n/g' "$1" | grep -v '^[[:space:]]*$'; }
diff <(strip server.html) <(strip hydrated.html) | head -50

Lines marked < exist only in the server HTML, and lines marked > exist only after hydration. The tag stripping is rough, but it is enough to spot a placeholder, a different date or a missing section. On Linux, call google-chrome instead of the macOS path.

For Google specifically, Google suggests the URL Inspection tool to look at the rendered HTML, and its live test adds a screenshot of the rendered page, which confirms the hydrated side for that crawler.

How to fix mismatches without hiding content

The three standard fixes change what crawlers read, so choose by where the content should live:

FixServer HTMLAfter hydrationUse for
Render the same data on both sidesFull contentSame contentAnything you want crawlers to read
Two-pass render with useEffectThe server branchThe client branch, after an extra renderSmall client-only details
suppressHydrationWarningServer textServer text, unpatchedA single timestamp that must differ
dynamic(..., { ssr: false })Nothing for that componentThe componentWidgets with no indexable content

The first is the real fix. Fetch the data on the server and send it with the HTML, so the client hydrates from the same snapshot. If you use TanStack Query or SWR, prefetching on the server covers how to pass that snapshot down. Format dates and numbers on the server, or with a fixed locale and time zone on both sides.

The useEffect pattern, which both React and Next.js document, makes the first client render match the server and then updates. It removes the error, but the server branch is still what non-rendering crawlers read, so make that branch the meaningful one: render the content, and let the effect add the client-only detail.

Next.js describes ssr: false as a way to avoid mismatches by disabling prerendering for a component; in the App Router it only works in Client Components, and Next.js shows an error if you use it in a Server Component. That also removes the component from the raw HTML for every crawler that does not run JavaScript. Keep it for chat widgets, maps and similar tools, never for product details, prices or article text. Next.js and AI search covers the related client-side bailouts.

Showing a different version to people and to crawlers on purpose is a separate matter; if you are tempted to branch on the user agent instead, read serving AI crawlers different content first.

Frequently asked questions

Do hydration errors hurt SEO?

The error itself is a browser console message that crawlers do not report. The risk is that the server HTML and the hydrated page differ, so Googlebot, which indexes the rendered page, and non-rendering crawlers, which read the server HTML, can see different text, links or metadata.

Does Googlebot see the server version or the client version?

Googlebot renders the page and Google uses the rendered HTML for indexing, so after React re-renders a mismatched tree, Google should index the client output. Attributes React did not patch, and text under suppressHydrationWarning, can keep their server values.

Is suppressHydrationWarning safe for SEO?

It is safe for a single value that must differ, such as a timestamp, because React keeps the server text and every crawler reads that. React says it works one level deep and is an escape hatch, so it is not a fix for content that is missing or wrong on the server.

It cannot block a crawler, but a typeof window branch or ssr: false component can leave the server HTML with a placeholder where your content should be. Crawlers that do not run JavaScript then read the placeholder, whatever the page looks like in a browser.

Check what the server sends

Run the console diff on your most important templates and fix any row where the title, H1, main text or canonical differ. To see whether a page's raw HTML carries its content for AI crawlers, run the free check on one URL; for every public template, an audit reports the gaps with evidence and prioritized fixes.

Filed under Rendering and content. Topics: react, nextjs, ssr, rendering, raw-html