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,classorcontentattribute 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:
| Reader | Runs JavaScript | Reads after a mismatch |
|---|---|---|
| Non-rendering crawlers: the major AI crawlers in public measurements so far, and any HTTP client such as curl | No | The server HTML, exactly as sent |
| Rendering crawlers: Googlebot, after its render queue | Yes | The DOM after hydration and any client re-render |
| A person in a browser | Yes | Same 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.
| Cause | Server HTML (non-rendering crawler) | After hydration (rendering crawler) |
|---|---|---|
typeof window !== 'undefined' branch | The server branch | The client branch |
Browser-only APIs (window, localStorage, matchMedia) in render | A default value, or a crash on the server | The value in that browser |
Date(), Date.now(), Math.random() | The value at render time on the server | The value at hydration time |
| Date formatting in the user's locale | The server's locale and time zone | The browser's locale and time zone |
| External data that changed, with no snapshot sent | The data the server fetched | The data the client fetched |
Invalid HTML nesting, such as <div> inside <p> | Markup the HTML parser restructures | React's client tree |
| Browser extensions, iOS format detection | Unaffected | Unaffected for crawlers; differs only for some visitors |
| Edge or CDN tools that rewrite the HTML | The rewritten HTML | Client 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:
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:
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:
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 -50Lines 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:
| Fix | Server HTML | After hydration | Use for |
|---|---|---|---|
| Render the same data on both sides | Full content | Same content | Anything you want crawlers to read |
Two-pass render with useEffect | The server branch | The client branch, after an extra render | Small client-only details |
suppressHydrationWarning | Server text | Server text, unpatched | A single timestamp that must differ |
dynamic(..., { ssr: false }) | Nothing for that component | The component | Widgets 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.
Can a hydration error remove my page from AI search?
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