You upgrade to React 19, move some components into the App Router, ship it — and the console lights up with a wall of red text about the server HTML not matching the client. Nothing about the app looks broken. Users probably won't notice. But under the hood, React just threw away your fast server-rendered markup and re-rendered the whole tree on the client, which is exactly the cost you upgraded to Server Components to avoid.

The good news: in practice there are really only three culprits behind most of these errors, and each one has a clean fix that doesn't involve sprinkling useEffect everywhere and hoping.

Why hydration mismatches hurt more than they look

When the server-rendered DOM doesn't match what React expects to render on the client, React can't reconcile the two trees. It falls back to discarding the server HTML and doing a full client-side render instead. That's not a cosmetic problem — it directly hits Cumulative Layout Shift and Interaction to Next Paint, the two Core Web Vitals that are hardest to claw back once they're bad. If you're seeing CLS spikes after a React 19 migration, check the console for hydration warnings before you go chasing anything else.

Cause 1: reading localStorage or window during render

Server-Side Rendering runs in Node.js or an edge runtime, where window and localStorage simply don't exist. If a component reads one of them directly during render — say, to pull a saved theme preference — the server has no choice but to output some default value. The browser then renders whatever's actually in storage. Different output, same component, instant mismatch.

The reflexive fix is a useEffect that sets state after mount. It works, but it also means every user sees a flash of the default value before the real one kicks in. React 19's useSyncExternalStore handles this properly, because it lets you specify a separate snapshot for the server render:

// src/hooks/useLocalStorage.ts
import { useSyncExternalStore } from 'react';

function subscribe(callback: () => void) {
  window.addEventListener('storage', callback);
  return () => window.removeEventListener('storage', callback);
}

export function useClientStorage(key: string, initialValue: string): string {
  return useSyncExternalStore(
    subscribe,
    () => localStorage.getItem(key) ?? initialValue, // client snapshot
    () => initialValue // server snapshot — matches initial HTML exactly
  );
}

The server snapshot function guarantees the first client render matches what the server sent, so there's nothing to reconcile. You still get the flash if the stored value differs from your default, but at least it's a deliberate one-frame update rather than a hydration error in the console.

Cause 2: dates and timestamps that render differently by timezone

This one's sneaky because it works fine in local dev and then breaks the moment you deploy. new Date().toLocaleDateString() on the server resolves against the server's timezone — UTC, if you're on most serverless platforms — while the same call in the browser resolves against whatever timezone the visitor's machine is set to. Someone in IST and your Lambda function in UTC will produce two different strings for the same instant.

A two-pass render fixes it: show a fixed, timezone-independent format on both the server and the very first client render, then swap to the localized version once the component has mounted.

// src/components/FormattedTimestamp.tsx
'use client';

import { useState, useEffect } from 'react';

export function FormattedTimestamp({ dateString }: { dateString: string }) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  const dateObj = new Date(dateString);

  // Server + first client paint: fixed UTC format, no ambiguity
  if (!mounted) {
    return <time dateTime={dateString}>{dateObj.toISOString().slice(0, 10)}</time>;
  }

  // After hydration: localized to the visitor's timezone
  return (
    <time dateTime={dateString}>
      {dateObj.toLocaleDateString(undefined, {
        month: 'short',
        day: 'numeric',
        year: 'numeric',
      })}
    </time>
  );
}

Unlike the localStorage case, this one genuinely needs the mounted flag pattern rather than useSyncExternalStore — you're not subscribing to an external store, you're deliberately choosing to defer a formatting decision until you know which timezone you're rendering for. The brief flash from UTC-ISO to localized date is a fair trade for not shipping a hydration error.

Cause 3: browser extensions rewriting the DOM before React touches it

This is the one that has nothing to do with your code and everything to do with what's installed in the user's browser. Password managers like 1Password and Bitwarden, grammar checkers like Grammarly, and translation extensions all inject attributes — things like data-grammarly-id or fdprocessedid — directly into your DOM before React gets a chance to hydrate. React sees attributes on the server HTML that don't match what it rendered, and it complains.

You can't control the extension, so the fix is scoped suppression:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className="antialiased font-sans">
        {children}
      </body>
    </html>
  );
}

Two things worth knowing here that trip people up: suppressHydrationWarning only suppresses shallow attribute mismatches on the exact element it's placed on, and it doesn't cascade to children. Put it on <html> to cover extension noise there, and leave the rest of your tree with strict checking intact. If you're tempted to slap it everywhere to make warnings go away, don't — you'll end up masking real bugs along with the extension noise.

Quick reference

That last row matters: suppressHydrationWarning is for things genuinely outside your control, not a patch for broken markup. If your JSX is nesting a <div> inside a <p>, fix the JSX.

The pattern underneath all three

Every one of these fixes does the same thing: give the server and the first client render an identical, deterministic output, then let the "real" client-only value take over after mount. useSyncExternalStore's server snapshot argument, the mounted boolean, and suppressHydrationWarning are three different mechanisms for the same underlying move. Once you see that, diagnosing a new hydration error gets a lot faster — the question is never "why is React confused," it's "where in this component is something reading client-only state during the render that's supposed to match the server."