react hydration_error ai_generated true

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

ID: react/hydration-mismatch

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
75Evidence
2022-03-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
18 active — — —

Root Cause

Server and client render different HTML. Common causes: browser-only APIs (window, localStorage), date/time rendering, browser extensions injecting elements, and conditional rendering based on client state.

generic

Workarounds

  1. 90% success Use a mounted state to defer client-only rendering 
    const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []); if (!mounted) return <ServerFallback />; return <ClientContent />; This renders the same fallback on server and client until hydration completes.

    Sources: https://react.dev/reference/react-dom/client/hydrateRoot

  2. 88% success Move browser-only APIs behind typeof window checks 
    const value = typeof window !== 'undefined' ? window.localStorage.getItem('key') : null; This ensures server and client render the same default value initially.
  3. 92% success Use next/dynamic with ssr: false for truly client-only components 
    const ClientOnly = dynamic(() => import('./ClientOnly'), { ssr: false }); This skips server rendering for components that fundamentally cannot run on the server (maps, editors, etc.).

    Sources: https://nextjs.org/docs/app/building-your-application/optimizing/lazy-loading

Dead Ends

Common approaches that don't work:

  1. Adding suppressHydrationWarning to the root element 70% fail

    suppressHydrationWarning only suppresses text content mismatches on a single element. It does not fix structural mismatches (different elements, different number of children). It masks the problem rather than fixing it.

  2. Wrapping everything in useEffect to skip server rendering 80% fail

    Moving all rendering to useEffect means nothing renders on the server, defeating the purpose of SSR entirely. The page appears blank until JavaScript loads, hurting performance and SEO.

  3. Disabling React strict mode to suppress the error 90% fail

    Strict mode does not cause hydration errors. It double-invokes effects to catch bugs, but hydration mismatches are real rendering inconsistencies. Disabling strict mode does not fix them.

Error Chain

Frequently confused with: