Gigawave | Full-Stack App Development

Next.js
Hydration
SSR
Debugging

Understanding and Fixing Hydration Errors in Next.js

The Complete Guide to Solving the 'Text content does not match' Warning

Amit Hariyale

Full Stack Web Developer, Gigawave

8 min read · June 14, 2025

Hydration errors are among the most common and frustrating issues in Next.js development. These errors occur when there's a mismatch between server-rendered HTML and client-side JavaScript. This guide will help you understand why they happen and how to fix them permanently.

Why Hydration Errors Occur

Mismatch between server and client HTML
Browser-specific APIs used during server rendering
Inconsistent date/time formatting between server and client
Third-party libraries not SSR-compatible
Incorrect use of useEffect/useLayoutEffect hooks

Did You Know?Hydration errors only occur in development mode? In production, React will silently reconcile differences, potentially causing layout shifts!

The Classic Hydration Error Message

You've probably seen this warning in your console:

bash

Warning: Text content did not match. Server: "Hello" Client: "World"
Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.

Step 1: Understanding the Hydration Process

The Hydration Process	The hydration process in Next.js involves the following steps:
Server Rendering	Next.js generates HTML on the server
Initial Hydration	React attaches event handlers to server HTML
Mismatch Detection	React compares server and client output
Error Thrown	Differences trigger hydration error

Hydration is React's process of attaching to server-generated HTML and making it interactive.

Step 2: Common Causes and Fixes

Browser-Specific APIs

Accessing window or documentdirectly during server rendering:

components/BrokenComponent.tsx

// ❌ Wrong: Accessing window during render
function BrokenComponent() {
  const width = window.innerWidth;  // Server: undefined, Client: 1200
  return <div>Width: {width}px</div>;
}

components/FixedComponent.tsx

// ✅ Fixed: Use useEffect + useState
function FixedComponent() {
  const [width, setWidth] = useState(0);
  
  useEffect(() => {
    setWidth(window.innerWidth);
    const handleResize = () => setWidth(window.innerWidth);
    window.addEventListener('resize', handleResize);
    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return <div>Width: {width}px</div>;
}

Date/Time Mismatches

Formatting dates differently on server and client:

components/DateComponent.tsx

// ❌ Wrong: Inconsistent formatting
function DateComponent() {
  const date = new Date().toLocaleDateString(); 
  // Server: "7/5/2025", Client: "05/07/2025" (different locales)
  return <div>Today: {date}</div>;
}

components/FixedDateComponent.tsx

// ✅ Fixed: Use consistent timezone/locale
function FixedDateComponent() {
  const [date, setDate] = useState('');
  
  useEffect(() => {
    setDate(new Date().toLocaleDateString('en-US'));
  }, []);

  return <div>Today: {date}</div>;
}

Third-Party Library Issues

Libraries that aren't SSR-compatible:

components/MapComponent.tsx

// ❌ Wrong: Directly using non-SSR library
import { Map } from 'non-ssr-map-library';

function LocationMap() {
  return <Map center={[51.505, -0.09]} />;  // Fails on server
}

components/FixedMapComponent.tsx

// ✅ Fixed: Dynamic import with no SSR
import dynamic from 'next/dynamic';

const Map = dynamic(() => import('non-ssr-map-library').then(mod => mod.Map), {
  ssr: false
});

function FixedLocationMap() {
  return <Map center={[51.505, -0.09]} />;
}

Step 3: Advanced Fixes

Suppressing Hydration Warnings

For safe differences (like unimportant whitespace):

pages/index.tsx

// Add suppressHydrationWarning to ignore specific differences
<div suppressHydrationWarning={true}>
  {new Date().toLocaleTimeString()} 
</div>

Using useLayoutEffect

For DOM measurements that need to happen before paint:

components/MeasureComponent.tsx

import { useLayoutEffect, useRef } from 'react';

function MeasureComponent() {
  const ref = useRef(null);
  
  useLayoutEffect(() => {
    const { width } = ref.current.getBoundingClientRect();
    console.log('Width:', width);
  }, []);

  return <div ref={ref}>Content</div>;
}

Pro Tips for Avoiding Hydration Errors

Always initialize state with consistent values
Use CSS for layout shifts instead of JS
Prefer data fetching in getServerSideProps/getStaticProps
Test with different locales and timezones
Verify third-party library SSR compatibility

Hydration Error Checklist	Common issues that cause hydration errors
Browser APIs	Moved to useEffect/useLayoutEffect
Dates/Times	Consistent formatting on server/client
External Libraries	Using dynamic imports with ssr:false
State Initialization	Consistent initial values
CSS-in-JS	Proper server-side rendering config

Best Practices

Always render the same component tree on server and client
Use the 'use client' directive strategically
Abstract browser-specific code into custom hooks
Implement error boundaries for graceful failures
Use Next.js' built-in ESLint rules for hydration checks

Essential Resources

Final Thoughts

Hydration errors can be tricky, but understanding their root causes makes them much easier to solve. Remember that consistency between server and client rendering is key - when in doubt, move browser-specific logic to useEffect or useLayoutEffect hooks.

By following these patterns and best practices, you'll eliminate hydration errors and create more robust Next.js applications with smoother user experiences.

Next Blog