, nested
tags, a
, or nested interactive elements such as an inside an . The HTML parser fixes the markup while building the DOM, so the tree React finds is not the tree it sent. how to tell: The message names an element mismatch rather than a text mismatch, and the same markup fails identically in every browser 2. [primary] Rendering logic that branches on the environment typeof window !== 'undefined', or reading window, localStorage, or matchMedia during render, produces one output on the server and a different one on the client by construction. how to tell: Removing the branch makes both renders agree; the mismatch is deterministic 3. [common] A value that differs between the two renders new Date(), Date.now(), Math.random(), locale-formatted output, or data fetched separately on each side. Timestamps are the classic case, since the server renders at build or request time and the client renders later. how to tell: The mismatched text is a date, a random id, or a locale-formatted number 4. [common] A browser extension mutating the DOM before hydration Password managers, translators, and accessibility tools inject attributes or wrapper nodes into the served HTML. This reproduces for affected users only and never in a clean profile. how to tell: Reproduces in a normal profile but not in an incognito window with extensions disabled 5. [edge] A misconfigured CSS-in-JS library Styles collected on the server but not flushed into the initial HTML change class names between the two renders. how to tell: The mismatch is confined to className attributes 6. [edge] An edge or CDN layer rewriting the HTML in flight HTML minification or injection performed after the response leaves the origin makes the delivered markup differ from what React rendered. how to tell: The origin response and the CDN response differ when compared byte for byte SOLUTION ------------------------------------------------------------------------ 1. Read which element or text the error names, then check that region for invalid nesting first. This is the cheapest cause to rule out and the most common one. 2. Move genuinely client-only logic out of render and into an effect, so the first client render still matches the server. 'use client'; import { useState, useEffect } from 'react'; export function ClientOnlyClock() { const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []); // First client render matches the server; the clock appears after mount. if (!mounted) return null; return ; } 3. For a component that can never render on the server, skip prerendering it entirely instead of guarding every branch inside it. import dynamic from 'next/dynamic'; const Chart = dynamic(() => import('../components/chart'), { ssr: false }); note: ssr: false is only permitted in Client Components in the App Router. 4. Where a difference is unavoidable and confined to one element's text, silence it deliberately with suppressHydrationWarning. note: It applies one level deep only and React will not patch mismatched text, so it is an escape hatch rather than a fix. 5. If the mismatch only reproduces for real users, test in a clean profile with extensions disabled before changing application code. 6. On iOS, stop Safari's automatic detection of phone numbers, dates, and addresses from rewriting text nodes into links. 7. Rule out the delivery layer by comparing the origin HTML with what the CDN serves; disable HTML auto-minification if they differ. VERIFY: Load the page with a production build and an empty browser profile: the console should show no hydration warning, and the rendered output should be identical before and after hydration. FALLBACK: If the mismatch cannot be localised, bisect by rendering subtrees behind the mounted flag one at a time until the warning disappears; the last subtree re-enabled contains the cause. APPLIES TO ------------------------------------------------------------------------ React: 18 and later (Applies to hydrateRoot; React 18 changed mismatches from patch-up to a hard error.) Next.js: 13 and later (Applies to both the App Router and the Pages Router wherever SSR or SSG is used.) runtimes: Node.js, Edge runtime NOT APPLICABLE TO ------------------------------------------------------------------------ - Client-side-only React applications created without server rendering, which never hydrate - Build-time errors, which fail before any HTML reaches the browser - React error #185, an infinite update loop, which is a render-phase setState problem - Content mismatches caused by an intentionally different client render after mount, which are not hydration errors EVIDENCE ------------------------------------------------------------------------ 1. Text content does not match server-rendered HTML https://nextjs.org/docs/messages/react-hydration-error Vercel | official-docs | read 2026-08-07 supports: The enumerated causes — invalid nesting, typeof window checks, browser-only APIs, time-dependent APIs, browser extensions, CSS-in-JS misconfiguration and CDN auto-minify — and the three prescribed fixes plus the iOS format-detection meta tag. 2. hydrateRoot — Handling different client and server content https://react.dev/reference/react-dom/client/hydrateRoot Meta Open Source | official-docs | read 2026-08-07 supports: That the client tree must produce the same output as the server, that mismatches should be treated as bugs, and that suppressHydrationWarning works one level deep and does not patch text. 3. HTML Standard — Interactive content https://html.spec.whatwg.org/multipage/dom.html#interactive-content WHATWG | specification | read 2026-08-07 supports: The content model that makes nested interactive elements invalid, which is why the parser restructures such markup during DOM construction. 4. Bug: Hydration mismatch error due to plugins generating script tag on top https://github.com/react/react/issues/24430 React | github-issue | read 2026-08-07 supports: That DOM mutations performed by browser extensions before hydration are a known source of mismatches outside the application's control. Note that Next.js links this issue under the old facebook/react path, which no longer resolves. CONFIDENCE ------------------------------------------------------------------------ high — The cause list and every prescribed fix are taken from the framework's own error page and React's hydrateRoot reference, with the nesting rules traced back to the HTML Standard. The bisection fallback is a debugging technique rather than a documented procedure and is presented as such. ------------------------------------------------------------------------ knowbase 0.1.0 — CC-BY-4.0