Skip to content

Warning: Text content did not match. Server: 'X' Client: 'Y'

Error message

                Text content did not match. Server: 'X' Client: 'Y'
              

Quick summary

The HTML rendered on the server doesn't match what React renders on the client during hydration, causing a mismatch warning.

Why this happens

  • Using Date.now(), Math.random(), or other non-deterministic values in render

  • Browser-only APIs (window, localStorage) used during SSR

  • Different data on server vs client (e.g., user session)

  • Improper use of useEffect for client-only rendering

Minimal example

✗ Broken code
function Clock() {
  return <div>{new Date().toLocaleTimeString()}</div>; // Different on server and client!
}
✓ Fixed code
function Clock() {
  const [time, setTime] = useState(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);
  return <div>{time || "Loading..."}</div>;
}

Moving the Date call to useEffect ensures it only runs on the client, avoiding the server/client mismatch.

How to diagnose

  • Look for Date.now(), Math.random(), or Date in render

  • Check for window/document/localStorage usage in render

  • Compare server and client output to find the difference

How to fix

  • Move non-deterministic code to useEffect (runs only on client)

  • Use typeof window !== 'undefined' guards for browser APIs

  • Use suppressHydrationWarning for intentional differences

  • Render a loading state until client-side data is ready

How to prevent

  • Never use non-deterministic values in render

  • Guard browser-only APIs with typeof checks

  • Use useEffect for client-only side effects

Related Resources

Related Glossary

Related Lessons

← Back to language