Framework InternalsBaseline · Widely

Hydration Mismatch & Subtree Bailout Mechanics

Mental Model

During hydration, the runtime walks existing server DOM nodes with a cursor while executing components. When client output diverges from server markup, the engine bails out of Resumability vs Hydration recovery, tears down the subtree, and re-renders inside the nearest Streaming SSR boundary.

Interactive Simulator

Hydration Cursor & Subtree Bailout

Trace how a DOM cursor detects SSR mismatches and isolates client re-renders to Suspense boundaries.

App Root (matched)
<Suspense> Boundary
<time> Mismatch
Step 1 / 3: 1. Walk Server DOM Cursor

Hydrator matches <main> and <section> against server HTML without creating new DOM nodes.

tryToClaimNextHydratableInstance(fiber);
Internal State / Memory
cursorNode
<time>
serverText
14:00:00 UTC
clientText
06:00:00 AM

Under the Hood

Hydration attaches event listeners and internal fiber pointers to pre-existing DOM nodes without recreating them.

  1. DOM Cursor Walk: As each component renders, the hydrator advances nextHydratableInstance across child Element and Text nodes, verifying tag names and critical text content.
  2. Mismatch Detection: Non-deterministic inputs (Date.now(), Intl.DateTimeFormat timezone differences, window.innerWidth) produce a client virtual node that fails tag or text comparison against the cursor.
  3. Subtree Bailout: On mismatch, React throws a recoverable hydration error, walks up to the nearest <Suspense> boundary (or root), deletes the server DOM inside that boundary, and schedules a client-only render pass.
TSX
function LocalTimestamp({ iso }: { iso: string }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  return (
    <time dateTime={iso}>
      {mounted ? new Date(iso).toLocaleTimeString() : iso.slice(11, 19) + ' UTC'}
    </time>
  );
}

Problem Genealogy

  • 2015 (ReactDOM.render Checksum): React hashed rendered markup with adler32; any single-character mismatch nuked the entire document.body and rebuilt it synchronously.
  • 2017 (hydrate() Per-Node Patching): Switched to per-node cursor walking and patched mismatched attributes in place, leaving structural mismatches silent and buggy.
  • 2022 (hydrateRoot + Suspense Bailouts): Enforced strict tree matching while isolating bailouts to <Suspense> boundaries so a footer mismatch no longer destroys the hero section.

Production Pitfalls

Production Pitfall
  • Root-Level Bailouts: Placing no <Suspense> boundaries above a mismatched component forces the hydrator to discard the entire page DOM, spiking Total Blocking Time by 150–400 ms.
  • Browser Extensions Mutating <body>: Extensions that inject <style> or <div> siblings directly into document.body shift the cursor and trigger root mismatches if the app mounts directly on <body>.
When Not to Use
  • When not to use suppressHydrationWarning: Never slap suppressHydrationWarning on structural elements or containers with mismatched children; it only silences text/attribute warnings on a single leaf node and leaves wrong event targets attached.

Connections & Logical Next Steps

Framework InternalsHydration Mismatch & Subtree Bailout Mechanics
What This Unlocks
Leaf concept

Seen in Architecture Autopsies