Next.js hydration errors in production: what they mean for your site

Everything works on the developer's machine. Then, after a deploy, the error tracker starts filling up with messages like "Text content did not match server-rendered HTML" or "Hydration failed".

Sometimes users notice nothing. Sometimes a button does not respond, part of the page flickers, or the layout jumps. Either way, it is a sign that something is off.

What hydration is, in one paragraph

With Next.js, the server builds the page and sends ready-made HTML, so it loads fast and is good for SEO. Then the browser loads the JavaScript and "takes over" that HTML to make it interactive. This step is called hydration. For it to work, the page the browser builds has to match the page the server sent. When they differ, you get a hydration error.

Why it only happens in production

The server and the browser are two different environments. In production they differ in more ways than on a laptop: different time zones, different languages, real users with browser extensions, cached pages, and so on. Anything that makes the server and the browser produce different content can trigger the error.

Common causes

• Dates and times. The server formats a date in its own time zone, and the browser formats it in the user's time zone. The text does not match.
• Random values. Anything random or time-based that is generated while the page is being built will be different on the server and in the browser.
• Browser-only information. Things like screen size or saved user settings exist only in the browser. If the page uses them right away, the two versions differ.
• Invalid HTML. Some element combinations are not allowed, and the browser quietly "fixes" them, which creates a mismatch.
• Browser extensions. Translation tools, password managers and ad blockers can change the page before the app takes over.

The fix is usually small once the cause is found. Finding the cause is the hard part.

When to ask for help

If the errors are rare, appear only for some users, or cannot be reproduced locally, it can take a while to track them down. There is a follow-up post about hydration errors that only appear under load, and one about memory leaks, which often show up alongside them.

If you would like someone to look at your app, a Production Health Audit is a low-risk way to start: I review the code and send you a written list of what I found and how to fix it.