Hydration failed
The server-rendered HTML structure did not match the initial client-side render.
Usually happens because:
- ☑ Stray div tags inside p/span blocks
- ☑ Direct access to window/localStorage on render
- ☑ Dynamic dates outputting server-client mismatches
🔍 Quick Checklist:
📊 Where this usually happens (estimated occurrence)
What is Hydration failed?
In Server-Side Rendering (SSR) frameworks (like Next.js), the server compiles the React tree to static HTML, and the client 'hydrates' it by binding event listeners. If the HTML structure generated on the client differs from what the server sent, React cannot reconcile them, causing hydration failures.
Common Causes
- Nesting invalid HTML tags (like putting a <div> inside a <p> or another <div> inside a <span>).
- Accessing client-only globals (like window, localStorage, or dates) during initial render.
- Varying content dynamically based on navigator locale settings on the server.
Common Mistakes
- Checking `typeof window !== 'undefined'` directly inside render scopes to output different HTML layouts.
How to Fix
Framework-Specific Examples
No framework examples required for this informational status.
Wrong: Nested div inside p tag
export default function Component() {
return <p><div>This is invalid HTML nesting.</div></p>;
}Correct: Correct Nesting Blocks
export default function Component() {
return <div><div>This is correct markup.</div></div>;
}Best Practices
- Verify HTML markup standards.
- Implement hydration checks or use client-only dynamic imports inside Next.js.
Frequently Asked Questions (FAQ)
Q: What is hydration?
Hydration is the process where React client-side scripts bind event listeners to static HTML pre-rendered by the server, turning it into an interactive app.
Q: Why does invalid nesting cause hydration errors?
Browsers automatically correct invalid nesting (e.g. moving a `div` out of a `p` tag). This changes the HTML structure, causing a mismatch when React tries to hydrate it.
Q: How do I handle client-only states safely?
Use a state variable `isMounted` which starts at false and is set to true inside a `useEffect`. Render client content only when `isMounted` is true.
Q: What frameworks trigger this warning?
Next.js, Remix, Astro, Gatsby, and any custom SSR implementations.