How to fix Hydration mismatch: the server-rendered page does not match the client in React

What this error means

Next.js uses server-side rendering (SSR) to generate HTML on the server and send it to the browser. When the page loads, React performs "hydration" - attaching event listeners and taking over the static HTML to make it interactive. A hydration mismatch happens when the HTML structure, text content, or attributes generated on the server do not match what React tries to render on the client. React expects the initial client render to produce identical output to the server HTML. When they differ, React cannot properly hydrate the page, leading to this error. The mismatch can be caused by environment differences (server vs browser), timing differences, or non-deterministic code that produces different results on each run.

Typical symptoms

• Console error "Hydration failed because the initial UI does not match what was rendered on the server"
• Warning "Text content does not match server-rendered HTML"
• Content flashing or changing immediately after page load
• Event handlers not working or attaching to wrong elements
• Visual flicker where content appears then disappears or changes
• Form inputs losing focus or values after initial render
• Random content differences between server HTML and client render
• CSS styles appearing broken briefly then correcting themselves

Common causes

1. Using browser-only APIs (window, document, localStorage, sessionStorage, navigator) during initial render without checking if they exist
2. Rendering timestamps, dates, or times that differ between server and client due to timezone or execution timing differences
3. Using Math.random() or other non-deterministic functions that produce different values on each render
4. Third-party browser extensions or scripts modifying the DOM before React hydrates (ad blockers, accessibility tools, auto-translators)
5. Invalid HTML nesting (div inside p tag, tr outside table, li outside ul/ol) causing browser to restructure the DOM
6. Using conditional logic based on client-specific values unavailable during SSR (screen width, user agent, geolocation)
7. Fetching different data on server versus client, causing structural differences in rendered HTML
8. Using dynamic imports or lazy-loaded components without proper SSR configuration in Next.js

How to fix "Hydration mismatch: the server-rendered page does not match the client"

# Example error output:
Warning: Text content did not match. Server: "Loading..." Client: "12/09/2025 3:45 PM"
  in div (at Component.tsx:12)

// WRONG - causes hydration mismatch
function WelcomeMessage() {
  const username = localStorage.getItem('username');
  return <div>Welcome {username}!</div>;
}

// CORRECT - server and client render the same initially
function WelcomeMessage() {
  const [username, setUsername] = useState<string | null>(null);
  
  useEffect(() => {
    setUsername(localStorage.getItem('username'));
  }, []);
  
  return <div>Welcome {username || 'Guest'}!</div>;
}

// WRONG - server and client times will differ
function Timestamp() {
  return <div>Page loaded at {new Date().toLocaleString()}</div>;
}

// CORRECT - use useEffect to update after hydration
function Timestamp() {
  const [timestamp, setTimestamp] = useState<string>('')
  
  useEffect(() => {
    setTimestamp(new Date().toLocaleString());
  }, []);
  
  return <div>{timestamp ? `Page loaded at ${timestamp}` : 'Loading...'}</div>;
}

// ALTERNATIVE - pass formatted date from server
export async function getServerSideProps() {
  return {
    props: {
      serverTime: new Date().toISOString()
    }
  };
}

// WRONG - div cannot be inside p
<p>
  <div>Content</div>
</p>

// WRONG - button cannot be inside button
<button>
  <button>Click me</button>
</button>

// CORRECT - use valid nesting
<div>
  <div>Content</div>
</div>

// For styled text, use span inside p
<p>
  <span className="highlight">Content</span>
</p>

<div suppressHydrationWarning>
  Rendered on server at {new Date().toISOString()}
</div>

import dynamic from 'next/dynamic';

// Component will only render on client, preventing hydration issues
const ClientOnlyComponent = dynamic(
  () => import('../components/ClientOnlyComponent'),
  { ssr: false }
);

export default function Page() {
  return (
    <div>
      <h1>My Page</h1>
      <ClientOnlyComponent />
    </div>
  );
}

// pages/posts/[id].tsx
export async function getServerSideProps({ params }) {
  const post = await fetchPost(params.id);
  return { props: { post } };
}

export default function Post({ post }) {
  // Both server and client receive same post data
  return <article>{post.content}</article>;
}

npm run build
npm run start
# Visit your app and check browser console for hydration errors

Advanced notes

Frequently asked questions

What does "Hydration mismatch: the server-rendered page does not match the client" mean?

js uses server-side rendering (SSR) to generate HTML on the server and send it to the browser. When the page loads, React performs "hydration" - attaching event listeners and taking over the static HTML to make it interactive. A hydration mismatch happens when the HTML structure, text content, or attributes generated on the server do not match what React tries to render on the client.

How do I fix "Hydration mismatch: the server-rendered page does not match the client"?

This error occurs when Next.js server-side renders HTML that differs from what React produces during client-side hydration. Common causes include using browser APIs, dynamic dates/times, or non-deterministic values during the initial render. The fix involves ensuring consistent rendering between server and client.

What causes "Hydration mismatch: the server-rendered page does not match the client"?

Using browser-only APIs (window, document, localStorage, sessionStorage, navigator) during initial render without checking if they exist Rendering timestamps, dates, or times that differ between server and client due to timezone or execution timing differences Using Math.random() or other non-deterministic functions that produce different values on each render

Is the "Hydration mismatch: the server-rendered page does not match the client" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Expected node.alt to be "string" but found "undefined"

  Image alt prop is undefined

  MEDIUM

• getStaticProps can only be used with pages

  getStaticProps can only be used with Pages Router

  MEDIUM

• Image with src="%s" was missing required "alt" property

  Image missing required "alt" property

  MEDIUM

• getServerSideProps can only be used with pages

  How to fix "getServerSideProps can only be used with pages" in React

  MEDIUM

• Failed to resolve import. Does the file exist?

  How to fix "Failed to resolve import" in React

  HIGH

• npm ERR! code ETIMEDOUT npm ERR! network request to https://registry.npmjs.org timed out

  npm registry request timed out

  MEDIUM

Official resources & further reading

• 📚React Official Documentation
• 📖
  Next.js official hydration error documentation(Official Docs)
• 📖
  React hydrateRoot API reference(Official Docs)
• 📝
  LogRocket guide to resolving hydration errors
• Netlify tutorial on fixing Next.js hydration errors
• 📝
  PropelAuth deep dive into hydration errors