# Error: Hydration failed because the initial UI does not match what was rendered on the server

**Code:** `Hydration failed` · **Category:** React · **Seen on:** React

The HTML rendered on the server differs from the first client render, so React (Next.js/Remix) can’t attach to it.

## Meaning

Server-side rendering requires the first client render to produce identical markup. Values that differ between server and browser — dates, random IDs, `window`/`localStorage`, locale formatting — or invalid HTML nesting cause mismatches.

## Common causes

- Rendering `Date.now()`, `Math.random()` or locale-dependent formatting
- Reading `window`, `localStorage` or media queries during render
- Invalid nesting (`<div>` inside `<p>`, `<a>` inside `<a>`)
- Browser extensions modifying the DOM
- Different data on server vs client

## Quick fix

1. Move browser-only values into `useEffect` (render a placeholder first)
2. Fix invalid HTML nesting
3. Use `suppressHydrationWarning` only for unavoidable text like timestamps
4. Render client-only components with `dynamic(() => import(...), { ssr: false })` in Next.js

## Detailed fix by platform

### React

1. Client-only value after mount:

```jsx
function LocalTime({ iso }) {
  const [text, setText] = useState('');               // same on server and first client render
  useEffect(() => setText(new Date(iso).toLocaleString()), [iso]);
  return <time dateTime={iso}>{text}</time>;
}
```


## How to diagnose

1. **Diff** — Which text/element differs (dev overlay shows it)?
2. **Browser APIs** — window/localStorage/Date used in render?
3. **HTML** — Invalid nesting?
4. **Extensions** — Reproduce in a clean profile

---
Source: [WhatIsMyError](https://whatismyerror.com/errors/react/hydration-failed)