Hydration failed because the initial UI does not match what was rendered on the server.
HTML-ul generat pe server (Next.js, Remix, SSR) diferă de ce randează React prima dată în browser. Cauzele tipice: typeof window, Date, Math.random sau localStorage folosite direct în randare și HTML invalid (div în p). Randează la fel pe ambele părți și mută valorile din browser în useEffect.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
La randarea pe server, pagina vine din server ca HTML gata făcut. În browser, React face hydration: randează aceleași componente și „lipește” evenimentele de HTML-ul existent, în loc să-l refacă. Pentru asta, prima randare din browser trebuie să producă exact același HTML ca serverul.
Când diferă (alt text, alt tag, un element în plus), React 18 aruncă Hydration failed..., renunță la HTML-ul de pe server și randează totul din nou în browser. Pagina pare să meargă, dar pierzi performanța SSR și apare o pâlpâire.
Surse frecvente de diferențe: typeof window !== "undefined" în JSX, new Date() / Date.now() / Math.random(), localStorage, extensii de browser care modifică DOM-ul și HTML invalid (un div în p, pe care browserul îl mută). Mesajul vine adesea împreună cu „Text content does not match server-rendered HTML” sau „Expected server HTML to contain a matching...”, care îți spun ce element diferă.
De ce apare: cauzele frecvente
1Verificare typeof window în randare
export default function Mediu() {
const eBrowser = typeof window !== "undefined";
return <p>{eBrowser ? "Browser" : "Server"}</p>;
}export default function Mediu() {
const [montat, setMontat] = useState(false);
useEffect(() => setMontat(true), []);
return <p>{montat ? "Browser" : "Server"}</p>;
}Pe server și la prima randare din browser montat e false, deci HTML-ul e identic. Efectul rulează doar în browser, după hydration.
2Ora sau valori aleatoare în JSX
<p>Generat la {new Date().toLocaleTimeString()}</p>const [ora, setOra] = useState("");
useEffect(() => setOra(new Date().toLocaleTimeString()), []);
<p>Generat la {ora}</p>Serverul și browserul rulează la momente diferite, deci ora diferă. Valoarea calculată în efect apare după hydration.
3HTML invalid
<p>
<div>Preț special</div>
</p><div>
<p>Preț special</p>
</div>Browserul corectează HTML-ul primit de la server (scoate div din p), deci DOM-ul nu mai seamănă cu ce randează React.
Repară eroarea, direct în pagină
Componenta de mai jos e folosită într-o aplicație Next.js și dă „Hydration failed because the initial UI does not match what was rendered on the server”, pentru că alege textul cu typeof window. Repar-o ca prima randare să fie aceeași pe server și în browser: pornește cu „Se încarcă...” și, după montare, #mediu să afișeze „Rulează în browser”.
import { useState, useEffect } from "react";
export default function App() {
const eBrowser = typeof window !== "undefined";
return (
<p id="mediu">{eBrowser ? "Rulează în browser" : "Se încarcă..."}</p>
);
}Indiciu
Ține într-o stare dacă s-a montat componenta și schimb-o într-un useEffect.
Reparația
import { useState, useEffect } from "react";
export default function App() {
const [montat, setMontat] = useState(false);
useEffect(() => {
setMontat(true);
}, []);
return (
<p id="mediu">{montat ? "Rulează în browser" : "Se încarcă..."}</p>
);
}De ce merge
Pe server window nu există, deci HTML-ul trimis conținea „Se încarcă...”, iar în browser prima randare dădea „Rulează în browser”. React a găsit textul diferit în timpul hydration și a aruncat eroarea.
Cu starea montat pornită de la false, prima randare este identică în ambele locuri. useEffect rulează doar în browser, după hydration, iar setMontat(true) produce o randare nouă cu textul final.
Alte forme ale mesajului
Error: Hydration failed because the initial UI does not match what was rendered on the server.Error: Text content does not match server-rendered HTML.Warning: Text content did not match. Server: "Server" Client: "Browser"Warning: Expected server HTML to contain a matching <div> in <p>.Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
Cum o eviți pe viitor
- Prima randare a unei componente trebuie să depindă doar de props și de starea inițială, nu de browser.
- Tot ce ține de browser (
window,localStorage, ora curentă, dimensiunea ecranului) citește înuseEffect. - Scrie HTML valid: fără
divînp, fărăaîna,trmereu întbody. - Testează pagina într-o fereastră fără extensii, ca să excluzi extensiile care modifică DOM-ul.
- Pentru componente pur de browser, în Next.js folosește
dynamic(() => import(...), { ssr: false }).
Întrebări frecvente
Eroarea apare doar la mine, nu și la colegi. De ce?
Probabil o extensie de browser (traducere, manager de parole, Grammarly) adaugă atribute sau elemente în pagină înainte ca React să facă hydration. Încearcă într-o fereastră incognito.
Pot ascunde eroarea cu suppressHydrationWarning?
suppressHydrationWarning funcționează doar pentru textul unui singur element (de exemplu o oră afișată) și doar un nivel. Folosește-l pentru diferențe intenționate și mici, nu ca reparație generală.
Apare și într-o aplicație Vite simplă?
Nu, pentru că acolo nu există HTML de pe server: createRoot randează totul în browser. Apare doar cu SSR (Next.js, Remix, Gatsby) sau cu hydrateRoot.
Erori înrudite
Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>. Ai pus un element bloc (div, ul, h2 sau o componentă care randează unul) în interiorul unui <p>, ceea ce HTML nu permite. Schimbă paragraful exterior în div sau elementul interior în span. Warning: ReactDOM.render is no longer supported in React 18. Use createRoot instead. Until you switch to the new API, your app will behave as if it's running React 17. Learn more: https://reactjs.org/link/switch-to-createroot Pornești aplicația cu ReactDOM.render, API-ul din React 17. În React 18 se folosește createRoot din "react-dom/client": createRoot(document.getElementById("root")).render(<App />). Până schimbi, aplicația rulează ca în React 17, fără funcțiile noi. React Hook useEffect has a missing dependency: 'id'. Either include it or remove the dependency array. Efectul folosește o valoare (prop sau state) care lipsește din lista de dependențe, deci nu rulează din nou când ea se schimbă. Adaug-o în listă: useEffect(() => {...}, [id]). Învață React de la zero, cu exerciții la fiecare lecție
Curs React: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
