Hydration Mismatch

What is a hydration mismatch?

Next.js and other SSR frameworks render HTML on the server, then "hydrate" that HTML on the client by attaching React's event handlers. If the initial client render produces different markup than the server sent, React throws a hydration error.

Common causes in AI-built apps:

• Using Date.now(), Math.random(), or new Date() directly in a component
• Reading localStorage or window during render
• Rendering based on navigator.userAgent on both server and client
• Third-party scripts injecting markup before React hydrates

Why it matters

Hydration errors are loud in development but subtle in production. A page can appear to work while silently being un-interactive, or it can flash the server HTML and then re-render everything client-side, destroying Core Web Vitals.

The fix pattern

For anything that must only run on the client:

'use client'
import { useEffect, useState } from 'react'
 
export function ClientOnly({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  if (!mounted) return null
  return <>{children}</>
}

Wrap the offending component in <ClientOnly> and the mismatch disappears.

See also

• Error boundary
• Deploy Next.js to production