Hydration errors are the most misdiagnosed class of bug we see in server-rendered React. The error text is long, the stack points at a framework file, and the fastest-looking fix — suppressHydrationWarning, or moving the component behind a useEffect mount flag — makes the message disappear without addressing what caused it. That trade is sometimes correct. Usually it hides a real defect and costs you a chunk of the server rendering you paid for.
Every hydration mismatch has the same shape: the HTML React rendered on the server and the tree React produced on its first client render are not the same. That is the whole model. The work is locating the disagreement and deciding which side is wrong.
What React actually does when it mismatches
During hydration React walks the server HTML and attaches to it, expecting the client render to produce the same elements, attributes, and text. When it finds a difference it cannot reconcile, it discards the server HTML for that subtree and re-renders it on the client. The page usually still looks right, which is why these errors survive for months in production.
What you lose is the point of server rendering for that subtree: the markup is thrown away and rebuilt, so content that was in the initial HTML gets painted later. On a subtree that contains your Largest Contentful Paint element, that is an LCP regression with a warning attached. Hydration failures are one of the few console warnings worth treating as a performance ticket.
In React 18 the error text was famously unhelpful. React 19 rewrote it: you now get a diff showing the server value and the client value, plus the component path down to the offending node. Before you spend an afternoon bisecting, check which React version the app is on — if it is 18, upgrading the error message alone may be the cheapest first move.
Step 1: Read the diff, not the stack
The stack trace in a hydration error mostly describes React internals. The useful part is the component path and the +/- lines. Find the deepest component name in the path that belongs to your codebase; the mismatch is in its render output or in something it passes down.
If the diff shows a text difference — - 3:04 PM / + 3:05 PM, or two different formatted numbers — you have a time or locale problem and can skip to step 3. If it shows an attribute or element difference, keep reading.
Step 2: Bisect when the path is not enough
Deeply nested trees and heavy component composition will sometimes give you a path that stops at a generic wrapper. Two techniques narrow it faster than staring at source:
First, view source on the server response — the real HTML, not the DevTools element inspector, which shows the tree after the client has rewritten it. Search for the text or attribute from the diff. Seeing where it appears in raw HTML, and what surrounds it, usually identifies the component immediately.
Second, bisect by removal. Comment out half the page's subtrees, reload, observe. Three or four reloads isolates the responsible subtree even in a large route. It feels crude; it is faster than reasoning about a component graph you did not write.
Step 3: The five causes
Almost every mismatch we diagnose falls into one of these.
Time and randomness. new Date(), Date.now(), Math.random(), and anything derived from them — relative timestamps, generated ids, shuffled lists — produce different values on the server and the client by construction. Relative-time labels ("2 minutes ago") are the single most common cause we see.
Locale and timezone. toLocaleString, Intl.DateTimeFormat, and Intl.NumberFormat without an explicit locale and timezone read the server's environment on the server and the user's environment in the browser. The server is probably UTC and probably en-US; your user in Berlin is neither. This one is nastier than it looks because it reproduces only for users whose settings differ from your build machine, which is why it usually gets reported from a market you do not test in.
Browser-only APIs read during render. window, localStorage, matchMedia, document.cookie. Reading these during render means the server branch and the client branch are different code paths. Theme toggles and responsive branches are the usual offenders: the server renders the light theme because it cannot read localStorage, and the client renders dark.
Invalid HTML nesting. A <div> inside a <p>, a <p> inside a <p>, a <div> inside a <tr>. The browser's parser silently restructures the DOM to make it valid, so the tree React sees no longer matches the tree React sent. The React 19 error calls this out explicitly; in 18 it presents as a baffling mismatch at a node that looks fine. This one is frequently introduced by a rich-text or markdown renderer that emits block elements inside a paragraph wrapper.
Extension and third-party DOM mutation. Password managers add attributes to inputs, translation extensions rewrite text nodes, and some analytics snippets inject elements before hydration runs. These are not your bug, and they are also not reproducible in a clean profile — which is the diagnostic: if it disappears in an incognito window with extensions off, stop looking at your code.
Step 4: Fix on the correct side
For time, locale, and formatting, make the value deterministic rather than deferring the render. Pass an ISO timestamp from the server and format it with an explicit locale and timeZone so both sides compute the same string. If the display genuinely must be the viewer's local time, render the absolute server-formatted value in the markup and upgrade it in an effect after mount; the user sees real content in the initial HTML either way.
For browser-only state like a stored theme, the standard fix is to get the value into the server render — a cookie the server can read, or a small inline script that sets a data-theme attribute on <html> before React hydrates. suppressHydrationWarning on the <html> element is the accepted pattern for exactly that script, because you are deliberately allowing one attribute to differ. That is what the escape hatch is for: a known, bounded, single-attribute difference. It suppresses one element's check, not its subtree's, and it is not a general silencer.
For invalid nesting, fix the markup. There is no other fix.
The pattern worth naming as a smell is const [mounted, setMounted] = useState(false) with a useEffect that flips it and a return null before it. It ends the warning by ensuring the component renders nothing on the server. If that component is above the fold, you have converted a hydration warning into a layout shift and an LCP regression, silently. There are legitimate uses — a component genuinely driven by matchMedia, for instance — but it should be a decision with a reason in a comment, not a reflex.
Step 5: Keep them from coming back
Hydration errors are cheap to catch and expensive to find later, so put one gate in CI: a Playwright run against a production build that fails on hydration errors in the console, covering your three or four highest-traffic routes. Development-mode double rendering under Strict Mode does not surface these; a production build against real server HTML does.
If you are on React 18 and chasing a mismatch you cannot reproduce, check locale and timezone before anything else, and test with a non-UTC TZ and a non-en-US locale in the browser. That reproduces the majority of the ones that escape staging.
The reason we treat this as a performance topic rather than a console-hygiene one: a mismatch in a large subtree means that subtree's server HTML was work you did and then threw away. Measure the LCP of the route before and after you fix it. If the number does not move, the mismatch was in a subtree that did not matter, and you can spend the afternoon on something that does.