◆Error Codes Wiki

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

Errorweb development

Overview

Fix Next.js hydration mismatch errors where server-rendered HTML differs from client-rendered output, causing React hydration failures and warnings.

Key Details

  • 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

Common Causes

  • 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

Steps

  1. 1Use 'use client' directive for components that use browser-only APIs
  2. 2Wrap browser-only code in useEffect or check typeof window !== 'undefined'
  3. 3For dynamic content (time, random): use suppressHydrationWarning on the element or render in useEffect
  4. 4Validate HTML nesting: ensure block elements are not inside inline elements
  5. 5Delay third-party script loading with next/script strategy='afterInteractive' or 'lazyOnload'

Tags

nextjshydrationssrmismatchreact

Related Items

browser-react-error-boundary-crashes

More in Web Development

browser-cors-error-explainedBrowser CORS Error Explained — Cross-Origin Request Blocked
Warning
browser-websocket-errorsBrowser WebSocket Errors — Connection Failed, Closed & Protocol Errors
Warning
browser-indexeddb-errorsBrowser IndexedDB Errors — Quota Exceeded, Blocked & Corruption
Warning
browser-localstorage-quota-exceededBrowser localStorage Quota Exceeded — Storage Limit & Alternatives
Warning
browser-service-worker-errorsBrowser Service Worker Errors — Registration, Cache & Update Failures
Warning
browser-webgl-context-lostBrowser WebGL Context Lost — GPU Rendering Failure in Browser
Warning

Frequently Asked Questions

The text rendered on the server differs from what React generates on the client. Common causes: locale-dependent formatting, Date.toLocaleString(), browser-specific text rendering, or browser extensions modifying the DOM.