react 18+ · JavaScript
The message
Hydration failed because the initial UI does not match what was rendered on the server
What it means
The HTML the server sent and what the browser produced on its first render differ, so React could not attach one to the other. Using new Date() or Math.random() during render, reading localStorage, or drawing differently based on window width guarantees two different answers — and so does markup the browser silently repairs, such as a <div> inside a <p>. The rule is to render exactly what the server rendered on the first pass and change it after useEffect has run; the cost is that the differing part appears a moment later and is absent from the server HTML. React 19 words the same situation as "the server rendered HTML didn't match the client" and prints a diff of what differed.
The fix
There is no one-line command for this. The explanation says what to look at instead.
- Printed by
- react 18+
- JavaScript
- 15
Browser and Node errors usually tell you what broke and not why the value became what it was — you read undefined, it was not a function, it was not JSON — so the place to fix is upstream of the line that threw, and silencing just that line with ?. and default values makes the same problem reappear further away in a form that is harder to recognise.
Reading an error message
- Read from the first line down. The lower you go the more it is about the tool’s internals; the cause is usually at the top.
- If there is a file and a line number, start there — not the top stack frame, but the topmost line that names a file you wrote.
- Search the message verbatim, but strip your own paths and variable names first; those are what stop the search from matching.
- The same condition is worded differently across tool versions. If results look wrong, add the version number to the query.
- Before pasting a fix, check what it throws away. Some of these cannot be undone.
Common questions
Q. What does “Hydration failed because the initial UI does not match what was rendered on the server” mean?
The HTML the server sent and what the browser produced on its first render differ, so React could not attach one to the other. Using new Date() or Math.random() during render, reading localStorage, or drawing differently based on window width guarantees two different answers — and so does markup the browser silently repairs, such as a <div> inside a <p>. The rule is to render exactly what the server rendered on the first pass and change it after useEffect has run; the cost is that the differing part appears a moment later and is absent from the server HTML. React 19 words the same situation as "the server rendered HTML didn't match the client" and prints a diff of what differed.
Q. How do I fix it?
There is no one-line command. The explanation above says what to look at instead.
Q. Which tool prints this?
react 18+. It sits under JavaScript, and the message runs to 15 words.