Fix Next.js hydration mismatch errors in the App Router (2026)

How do you diagnose and fix Next.js hydration mismatch errors?

Short answer

A hydration mismatch happens when the HTML generated on the server does not match the React tree produced during the browser's first render. As documented in the React hydrateRoot reference and the Next.js React hydration error guide, React expects the initial client render to produce output identical to the server-rendered DOM before attaching event listeners.

To fix a mismatch in the Next.js App Router:

1. Ensure every component renders the exact same initial markup on both the server and the first browser pass.
2. Move browser-only reads (window, localStorage, navigator, viewer timezone) into useEffect after keeping the initial state deterministic.
3. Fix invalid HTML nesting, or isolate third-party browser widgets behind a Client Component using next/dynamic with ssr: false.

Do not confuse a browser hydration mismatch with a production Server Component crash that displays an error.digest identifier—a digest means the server failed during rendering, whereas a hydration error means the server succeeded but the browser produced a different initial tree.

Symptoms

In development, Next.js surfaces an overlay or console error such as:

Hydration failed because the server rendered HTML didn't match the client.

In production builds, React logs minified errors alongside visible UI glitches: text that flashes from one value to another on load, layout shifts when React discards and recreates a subtree, or interactive controls that ignore clicks right after initial page load.

Diagnostic decision table

Use this table to isolate the root cause before changing component boundaries:

| Symptom | Likely cause | How to check | Fix | | :---------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | | Text changes right after load (timestamps, currency, numbers) | Unpinned Date, timezone, or locale formatting during render | Compare server timezone (often UTC) with local browser timezone via View Page Source | Pass an ISO string and format with an explicit locale and timeZone, or defer local formatting to useEffect | | UI flickers or throws on first load when reading theme or saved state | Branching on typeof window !== 'undefined' or reading localStorage during render | Search the component render body for window, document, localStorage, or matchMedia | Render a deterministic default state first, then sync browser storage inside useEffect | | Warning points to unexpected parent/child tags (<p>, <div>, <table>) | Invalid HTML nesting auto-corrected by the browser HTML parser | Inspect raw HTML vs. live DOM in DevTools Elements panel | Fix markup semantics (never nest <div> inside <p>, <p> inside <p>, or <button> inside another <button>) | | Mismatch appears only for some users or disappears in a clean browser profile | Browser extensions mutating the DOM or CDN edge transformations | Reproduce in a clean profile with all extensions disabled and compare origin HTML vs. CDN response | If an edge transform changes the HTML, disable that transform and compare again |

Why 'use client' alone does not fix hydration errors

A common misconception in the App Router is that adding 'use client' makes a component run only in the browser. In Next.js, Client Components are still prerendered on the server to produce the initial HTML response, and then hydrated on the client (Next.js hydration error guide).

If you branch on typeof window !== 'undefined' inside the render function, the server takes one branch while the browser's first render takes the other, causing a mismatch if the branches produce different markup. Instead, start with a stable initial state and read browser storage inside useEffect. Wrap storage access in try/catch so strict privacy modes or blocked storage do not throw at runtime (the code examples in this article are illustrative):

'use client';

import { useEffect, useState } from 'react';

type BannerPrefs = 'expanded' | 'compact';

export function DensityToggle() {
  // Stable initial state: matches on both server prerender and first client render
  const [density, setDensity] = useState<BannerPrefs>('expanded');

  useEffect(() => {
    try {
      const saved = window.localStorage.getItem('ui-density');
      if (saved === 'compact' || saved === 'expanded') {
        setDensity(saved);
      }
    } catch {
      // Ignore SecurityError when storage is blocked by browser privacy settings
    }
  }, []);

  return <div data-density={density}>View mode: {density}</div>;
}

Deterministic dates, invalid nesting, and external DOM mutations

Format dates deterministically from serialized ISO data

Calling new Date().toLocaleDateString() during render uses the server's clock and locale during SSR and the user's clock and locale during hydration. Pass a serialized ISO 8601 timestamp from your data layer and lock both the locale and timeZone when formatting during render:

const utcFormatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium',
  timeZone: 'UTC',
});

export function ReleaseDate({ publishedAtIso }: { publishedAtIso: string }) {
  return <time dateTime={publishedAtIso}>{utcFormatter.format(new Date(publishedAtIso))}</time>;
}

Fix invalid HTML nesting

Browsers repair invalid HTML before React hydrates. If a component renders a <div> or <section> inside a <p>, or omits <tbody> in a manually constructed <table>, the browser splits or inserts elements automatically. React then compares its virtual tree against the browser-repaired DOM and fails hydration. Fix the tag hierarchy directly rather than suppressing warnings.

Isolate browser extensions and CDN rewrites

Password managers, translation tools, and accessibility extensions often inject attributes or nodes before hydration finishes. Similarly, CDN features such as email obfuscation or HTML minification can rewrite text nodes in transit. Always test suspected hydration bugs in a clean browser profile with extensions disabled, and inspect curl output directly against your origin server to rule out edge HTML transforms.

Using ssr: false and suppressHydrationWarning safely

Defer a browser-only widget with ssr: false inside a Client Component

When a small third-party widget depends on browser layout APIs (ResizeObserver, canvas, or window globals on import), lazy-load it with next/dynamic and ssr: false. Per the Next.js lazy loading guide, ssr: false is only supported inside a Client Component—declaring ssr: false inside a Server Component triggers a build error:

'use client';

import dynamic from 'next/dynamic';

const ViewportChart = dynamic(() => import('./ViewportChart'), {
  ssr: false,
  loading: () => <div className="h-48 rounded border" aria-busy="true" />,
});

export function MetricsPanel() {
  return <ViewportChart />;
}

Keep ssr: false scoped to the leaf widget so surrounding content remains server-rendered. The widget itself has no prerendered content and needs JavaScript to appear. Avoid values such as Math.random() or crypto.randomUUID() during render; pass stable data instead.

Understand the limits of suppressHydrationWarning

If a single element's text or attribute unavoidably differs between server and client—such as a local relative timestamp—you can add suppressHydrationWarning to that element. However, as the React hydrateRoot documentation notes, suppressHydrationWarning only silences warnings one level deep, and React will not attempt to patch mismatched text content during hydration. Never use it to mask broken state logic; the user will continue seeing the stale server text until a subsequent state update occurs.

Practical verification before and after deployment

Do not rely solely on next dev or soft client-side navigation (<Link>) when verifying a fix, because soft navigation skips initial HTML hydration.

1. Build and run a production server (npm run build && npm run start).
2. Open the route in a clean browser profile with all extensions disabled.
3. Trigger a hard reload (Ctrl+Shift+R / Cmd+Shift+R) so the browser downloads fresh server HTML and runs hydrateRoot from scratch.
4. Confirm both conditions:
   • The browser console shows zero hydration warnings or errors.
   • Visible text, layout, and interactive controls work correctly; intentional post-mount updates from storage are expected, while unintended flashes or stale text need investigation.

Sources

• React Hydration Error (react-hydration-error) — Next.js Docs
• hydrateRoot Reference — React Docs
• Lazy Loading (next/dynamic and ssr: false) — Next.js App Router Guide
• Repository reference environment: Next.js 15.1.9 and React 19.0.0 (App Router). These reflect this repository's pinned dependencies rather than latest supported-version recommendations; code examples above are illustrative.

Internal links

• Parent hub: Next.js security
• Related:
  • Trace a Next.js error digest to the real server error
  • Fix "Failed to find Server Action" in Next.js after a deploy
  • Next.js security update playbook