...
Eroare React · Ce poți afișa în JSX

Hydration failed because the initial UI does not match what was rendered on the server.

Pe scurt

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

Greșit
JSX
export default function Mediu() {
  const eBrowser = typeof window !== "undefined";
  return <p>{eBrowser ? "Browser" : "Server"}</p>;
}
Corect
JSX
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

Greșit
JSX
<p>Generat la {new Date().toLocaleTimeString()}</p>
Corect
JSX
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

Greșit
JSX
<p>
  <div>Preț special</div>
</p>
Corect
JSX
<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ă tu

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”.

Codul care dă eroarea
JSX
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.

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 în useEffect.
  • Scrie HTML valid: fără div în p, fără a în a, tr mereu în tbody.
  • 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

← Toate erorile React

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.