Next.js Hydration Errors — Server-Client HTML Mismatch and SSR Issues

Fix Next.js hydration mismatch errors where server-rendered HTML differs from client-rendered output, causing React hydration failures and warnings. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: Hydration is the process where React attaches event handlers to server-rendered HTML. Hydration errors occur when the server HTML does not match what React expects to render on the client. Common mismatches: Date/time rendering, browser-only APIs (window, localStorage), random values. Next.js 13+ App Router shows more detailed hydration error messages than Pages Router. Invalid HTML nesting (e.g., <p> inside <p>, <div> inside <p>) also causes hydration errors. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Using Date.now(), Math.random(), or new Date() in rendered output — different on server and client. Accessing browser APIs (window, document, localStorage) during server-side rendering. Invalid HTML nesting that browsers auto-correct differently than the server renders. Third-party scripts modifying the DOM before React hydration completes. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Use 'use client' directive for components that use browser-only APIs. Wrap browser-only code in useEffect or check typeof window !== 'undefined'. For dynamic content (time, random): use suppressHydrationWarning on the element or render in useEffect. Validate HTML nesting: ensure block elements are not inside inline elements. Delay third-party script loading with next/script strategy='afterInteractive' or 'lazyOnload'. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Browser Errors collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.