title: Debugging Hydration Errors in Next.js slug: debugging-hydration-errors date: 2026-09-27 updated: 2026-09-28 description: A practical guide to the "Text content did not match" error and how to fix it. tags:
- nextjs
- react
- debugging draft: false
Hydration errors are one of the most confusing things to hit in a Next.js app. The error is vague, the stack trace points into React internals, and the actual cause is often three components away from where the error appears.
What hydration actually means
When Next.js renders a page, it does it twice:
- On the server — it produces HTML and sends it to the browser.
- On the client — React runs the same components again and "hydrates" the static HTML, attaching event listeners and state.
If the two renders produce different output, React throws a hydration error. The HTML the user sees doesn't match what React expected.
Why this matters
A mismatch isn't just a warning. React will discard the server-rendered tree and re-render from scratch on the client, which means:
- A visible flash of content changing
- Lost scroll position in some cases
- Slower time-to-interactive
For a static blog, you want hydration to succeed cleanly every time.
The three usual causes
1. Time or random values during render
This is the classic. Something like:
export function Timestamp() {
return <span>{new Date().toLocaleString()}</span>
}