Slik fikser du feilen «Hydration failed because the initial UI does not match»

Resultatet du ønsker, er enkelt å beskrive: HTML-en som produseres på serveren, må samsvare med det React produserer ved den første visningen i nettleseren. Når dette er tilfelle, kan React feste hendelsesbehandlere og gjøre siden interaktiv uten å kaste en hydreringsfeil, erstatte en undertre eller vise et uventet visuelt hopp.

Hydrering er prosessen der React tar HTML som allerede er gjengitt på serveren, og fester React-atferd til den i nettleseren. Reacts gjeldende dokumentasjon for hydrateRoot sier at klientgjengitt innhold forventes å være identisk med servergjengitt innhold, og at avvik bør behandles som feil.

Den nøyaktige ordlyden i feilmeldingen har endret seg over ulike versjoner av React og rammeverk. Du kan se en eldre melding som "Hydration failed because the initial UI does not match what was rendered on the server", eller en nyere melding som forklarer at treet gjengitt på serveren ikke samsvarte med klienten. Feilsøkingsprinsippet er det samme.

Versjonskontekst er viktig. Per 11. september 2026 lister den offisielle React-siden React 19.3 som den nyeste React-versjonen, mens den gjeldende Next.js-dokumentasjonen identifiserer Next.js 16.3.4 som den nyeste Next.js-utgivelsen. Sjekk Reacts versjonsside og den gjeldende Next.js-dokumentasjonen hvis du leser dette senere, fordi tilgjengelige API-er og feilmeldinger kan endre seg.

Hva teller som en vellykket fiks?

Døm ikke suksess kun etter om en rød utviklingsoverlay forsvinner. En god fiks bør oppfylle flere sjekkpunkter:

• Hydreringsadvarselen eller feilen vises ikke lenger ved en ren omlasting.
• Den opprinnelige servergjengitte brukergrensesnittet og nettleserens første React-visning representerer samme innhold og struktur.
• Den berørte komponenten forblir interaktiv etter hydrering.
• Det er ingen åpenbar blink fra én verdi til en annen, med mindre den endringen er tilsiktet og designet.
• Problemet forblir fikset i en produksjonsbygging, ikke bare på utviklingsserveren.
• Du har korrigert årsaken i stedet for å skjule et reelt avvik med et alternativ for advarselsundertrykkelse.

Hvis advarselen forsvinner, men siden nå gjengir viktig innhold først etter at JavaScript er lastet, kan feilen være borte mens brukeropplevelsen har blitt verre. Det kan være et rimelig kompromiss for en nettleseravhengig widget, men det er ikke automatisk det beste resultatet for primært sideinnhold.

Steg 1: Reproduser avviket og finn den minste feilende komponenten

Start med en hard omlasting i utviklingsmiljøet og les hele feilmeldingen, inkludert komponentstakken. React 19s dokumenterte hydreringsfeil lister flere vanlige årsaker: server/klient-grener som typeof window !== 'undefined', endrede verdier som Date.now() eller Math.random(), lokalavhengig datoformatering, ekstern data som endret seg uten et øyeblikksbilde, ugyldig HTML-nesting og nettleserutvidelser som endrer DOM-en. Se React-feil 418.

Next.js gir en lignende liste i sin offisielle guide for hydreringsfeil, og legger til nettleseravhengige API-er som window og localStorage, CSS-in-JS-konfigurasjon og HTML endret av et Edge/CDN-lag.

En praktisk isolasjonsmetode er å midlertidig erstatte mistenkelige dynamiske seksjoner med deterministisk tekst. Hvis feilen forsvinner, gjenopprett disse seksjonene én om gangen. Dette er vanligvis raskere enn å endre globale gjengivelsesinnstillinger før du vet hvilken komponent som er ansvarlig.

Kvalitetssignal

Du er klar til å gå videre når du kan navngi både den feilende komponenten og verdien eller strukturen som avviker. "Det skjer et sted i dashbordet" er fortsatt for bredt. "Tidsstempelet i StatusCard produseres uavhengig på server og klient" er handlingsbart.

Steg 2: Fjern ikke-deterministiske verdier fra den første gjengivelsen

Deterministisk gjengivelse betyr at de samme inndataene produserer samme første brukergrensesnitt. Verdier som endrer seg uavhengig mellom servergjengivelse og nettlesergjengivelse, er hyppige kilder til avvik.

Vurder dette problematiske mønsteret:

export default function LastUpdated() {
  return <time>{new Date().toLocaleString()}</time>;
}

Serveren og nettleseren kan kjøre denne koden på ulike tidspunkter og i ulike lokaliteter eller tidssoner. En bedre løsning avhenger av hva siden skal kommunisere.

Hvis tidsstempelet representerer serverdata, beregn eller hent det én gang på serveren og send den samme serialiserte verdien til klienten:

export default function LastUpdated({ isoTime }) {
  return <time dateTime={isoTime}>{isoTime}</time>;
}

Hvis verdien genuint avhenger av brukerens nettleser, gjengir du en stabil plassholder først og oppdaterer den etter hydrering.

'use client';

import { useEffect, useState } from 'react';

export default function LocalTime() {
  const [text, setText] = useState('Loading local time...');

  useEffect(() => {
    setText(new Date().toLocaleString());
  }, []);

  return <time>{text}</time>;
}

Dette fungerer fordi serveren og den første klientgjengivelsen begge produserer den samme plassholderen. Reacts useEffect-dokumentasjon beskriver dette to-trinns mønsteret for de sjeldne tilfellene der klientinnhold må avvike fra serverinnhold.

Når du bør endre tilnærming

Hvis den nettleseravhengige verdien er hele formålet med komponenten – for eksempel en editor gjenopprettet fra localStorage eller en widget som ikke kan gjengis meningsfullt på serveren – kan det å tvinge et plassholder-og-effekt-mønster gjennom hele komponenten legge til unødvendig kompleksitet. I så fall, bruk en bevisst nettleseravhengig grense i stedet for å late som om komponenten er servergjengibar.

Steg 3: Ikke les nettleseravhengige API-er under den første serverkompatible gjengivelsen

En vanlig misforståelse i Next.js er at å legge til 'use client' garanterer at komponenten kun gjengis i nettleseren. Det gjør den ikke. Next.js forklarer at Client Components er grensen for state, effekter, hendelsesbehandlere og nettleser-API-er, men Client Components kan fortsatt delta i forhåndsgjengivelse. Se den gjeldende use client-dokumentasjonen.

Dette mønsteret er risikabelt under gjengivelse:

'use client';

export default function ThemeLabel() {
  const theme = localStorage.getItem('theme') ?? 'light';
  return <span>{theme}</span>;
}

På serveren eksisterer ikke localStorage. Selv en gren som typeof window !== 'undefined' kan produsere ulik markup ved den første nettlesergjengivelsen, noe både React og Next.js dokumenterer som en årsak til hydreringsavvik.

For små forskjeller, flytt nettleseravlesningen til en Effect. For en komponent som genuint bør være nettleseravhengig i Next.js, kan du dynamisk laste den inn med SSR deaktivert:

'use client';

import dynamic from 'next/dynamic';

const BrowserOnlyChart = dynamic(
  () => import('./BrowserOnlyChart'),
  { ssr: false }
);

export default function Dashboard() {
  return <BrowserOnlyChart />;
}

Next.js dokumenterer ssr: false for Client Components i sin guide for treg lasting. Samme guide sier at ssr: false ikke støttes når du prøver å bruke det alternativet direkte i en Server Component; flytt den dynamiske importen inn i en Client Component.

React 19.3: et førsteklasses nettleseravhengig alternativ

React 19.3 introduserte browser-API-et. En komponent kan kalle use(browser()) inne i en Suspense-grense for å melde den komponenten ut av servergjengivelse. Serveren gjengir Suspense-plassholderen, mens komponenten gjengir normalt i nettleseren. Se Reacts browser API-referanse.

import { Suspense, use } from 'react';
import { browser } from 'react-dom';

function BrowserOnlyContent() {
  use(browser('Requires browser APIs'));
  return <ActualBrowserContent />;
}

export default function Example() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <BrowserOnlyContent />
    </Suspense>
  );
}

I en React Server Components-applikasjon sier React at use(browser()) må kalles fra en Client Component. Verifiser også at ditt rammeverk og installerte React-versjon eksponerer denne API-en før du tar den i bruk.

Steg 4: Gjør serverdata og den første klientdataen til samme øyeblikksbilde

Et øyeblikksbilde er den nøyaktige datastaten som brukes til å produsere den første HTML-en. Hydrering blir skjør hvis serveren gjengir én dataversjon og klienten umiddelbart leser en nyere eller ulikt sortert versjon før hydreringen er fullført.

For eksempel, la oss si at serveren gjengir en pris på $99, men klienten umiddelbart henter det samme produktet og får $109 før sin første gjengivelse. Problemet er ikke at dataene endret seg; endrede data er normalt. Problemet er at de to miljøene brukte forskjellige innledende inndata.

Et sterkt mønster er:

1. Hent de innledende dataene på serveren.
2. Gjengir HTML-en fra den dataen.
3. Send eller serialiser de samme innledende dataene til klientkomponenten.
4. Tillat klienten å revalidere og oppdatere seg hvis nyere data finnes, etter hydrering.

Den korrekte implementasjonen avhenger av rammeverkets datalastingsmodell, men kvalitetskriteriet forblir det samme: server-HTML-en og det første klienttreet bør basere seg på samme logiske tilstand.

Når du bør endre tilnærming

Hvis innholdet er iboende sanntids og et utdatert serverøyeblikksbilde ville villedet brukere – for eksempel en live-handelswidget eller en raskt endrende operasjonskonsoll – vurder å gjengir et stabilt skallet på serveren og laste den live-seksjonen på klienten. Det gir opp noe servergjengitt innhold for den regionen, men det kan være mer ærlig enn å hydrere mot data som er garantert å endre seg.

Steg 5: Fiks ugyldig HTML før du skylder på React

Nettlesere har lov til å korrigere feilformet eller ugyldig nestet HTML. Den korreksjonen kan produsere en DOM-struktur som avviker fra strukturen React forventer, selv om JSX-en så visuelt plausibel ut.

Next.js lister uttrykkelig eksempler som en <div> inne i en <p>, en liste inne i et avsnitt, nøstede anker-tagger og nøstede knapper som årsaker til hydreringsproblemer.

For eksempel, unngå:

<p>
  Intro text
  <div>Details</div>
</p>

<div>
  <p>Intro text</p>
  <div>Details</div>
</div>

Hvis et komponentbibliotek genererer markupen, inspiser den endelige DOM-en i stedet for å anta at wrapper-elementene er gyldige. En lint-regel eller HTML-validerer kan hjelpe, men nettleserens faktiske DOM er det React hydrerer.

Steg 6: Utelukk kode utenfor komponenten

Hvis gjengivelseslogikken din er deterministisk og HTML-en din er gyldig, sjekk om noe endrer server-HTML-en før React hydrerer den.

Offisiell Next.js-dokumentasjon nevner flere muligheter:

• En nettleserutvidelse endrer siden før React lastes.
• Et CSS-in-JS-bibliotek er feilkonfigurert for servergjengivelse.
• En Edge- eller CDN-funksjon omskriver eller minifiserer HTML-responsen.
• På iOS kan automatisk gjenkjenning av telefonnumre, e-postadresser, datoer eller adresser endre tekst til lenker i noen tilfeller.

Bruk kontrollerte sammenligninger. Test i et privat nettleservindu med utvidelser deaktivert. Hvis feilen oppstår kun bak en CDN, sammenlign med opprinnelsesresponsen. Hvis det startet etter at du tok i bruk et stylingbibliotek, følg det bibliotekets offisielle SSR-konfigurasjon i stedet for å anvende en generell hydreringsløsning.

Kvalitetssignal

Du har isolert denne klassen av problemer når samme applikasjonsbygging hydrerer korrekt i ett kontrollert miljø, men feiler etter at en spesifikk nettleserutvidelse, proxy, CDN-transformasjon eller integrasjon endrer HTML-en.

Steg 7: Bruk suppressHydrationWarning kun for en genuint uunngåelig lokal forskjell

React tilbyr suppressHydrationWarning={true} for sjeldne tilfeller der teksten eller attributtene til et enkelt element ikke rimelig kan samsvare, som visse tidsstempler.

<time suppressHydrationWarning>
  {new Date().toLocaleString()}
</time>

Dette er ikke en generell reparasjonsmekanisme. Reacts dokumentasjon for vanlige DOM-props sier at alternativet kun fungerer ett nivå dypt og er ment som en nødutgang. Next.js-hydreringsguiden advarer også om at React ikke vil prøve å lappe sammen mismatchet tekstinnhold når dette alternativet brukes.

• Forskjellen er forventet og lokalisert.
• Avviket representerer ikke feil applikasjonstilstand.
• Den omgivende strukturen er stabil.
• Du har bevisst akseptert at den innledende serververdien og nettleserverdien avviker.

Hvis å legge til prop-en får dusinvis av advarsler til å forsvinne, er det en grunn til å undersøke videre, ikke et tegn på at det underliggende problemet er løst.

Steg 8: Verifiser fiksen i utviklings- og produksjonsmiljø

Utviklingsatferd kan avvike fra en optimalisert produksjonsbygging. Etter at feilen er borte lokalt, utfør en produksjonsstil-sjekk for rammeverket ditt. For et typisk Next.js-prosjekt betyr det ofte å bygge og starte applikasjonen med dine normale pakkebehandlerkommandoer, og deretter gjøre nye navigasjoner og omlastinger.

Hvis du direkte eier React SSR-inngangspunktet i stedet for å bruke et rammeverk, støtter hydrateRoot også feilkallbakker som onRecoverableError, som kan hjelpe produksjonslogging. Rammeverkbrukere bør generelt ikke erstatte rammeverkets hydreringsinngangspunkt kun for å legge til tilpasset håndtering.

Når du bør prøve en annen gjengivelsesstrategi

I noen tilfeller er den beste fiksen ikke å tvinge en komponent inn i SSR. Vurder en annen gjengivelsesstrategi når:

• Komponenten er bygget rundt window, canvas, WebGL, nettlesermålinger eller et annet nettleseravhengig API.
• En tredjeparts-widget støtter offisielt ikke SSR.
• Komponentens meningsfulle innhold avhenger helt av enhetslokal state som localStorage.
• Sanntidsdata endres så raskt at det å matche et serverøyeblikksbilde har liten verdi.

I disse tilfellene kan en målrettet klientavhengig grense være renere. Nøkkelordet er målrettet. Å deaktivere SSR for en hel side for å akkommodere ett diagram eller en editor kan unnvære nyttig servergjengitt innhold, lasteadferd og andre fordeler unødvendig.

Vanlige fikser som ser vellykkede ut, men ikke er det

Grensene for disse fiksene

En hydreringsfeil forteller deg at server- og klientgjengivelse divergerte; den beviser ikke hvorfor. Det samme symptomet kan komme fra applikasjonslogikk, nettleserendring, et bibliotek, en CDN, feilformet HTML eller endrede data. Det finnes ikke én enkelt kodebit som trygt fikser alle disse tilfellene.

Videre, å fjerne hydreringsadvarsler garanterer ikke korrekthet andre steder. En klientavhengig komponent kan fortsatt ha datakappløp. En deterministisk første gjengivelse kan fortsatt vise utdaterte data etter hydrering. En gyldig DOM kan fortsatt inneholde tilgjengelighetsproblemer. Behandle hydrering som én kvalitetsport, ikke den eneste.

Reacts 19.3s nye browser-API betyr heller ikke at alle rammeverk umiddelbart bør erstatte sine etablerte nettleseravhengige mønstre. Rammeverkintegrasjon og installerte versjoner betyr noe. Hvis prosjektet ditt er på en eldre React- eller Next.js-utgivelse, følg dokumentasjonen for den utgivelsen i stedet for å kopiere en nyere API blindt.

En pålitelig beslutningsrekkefølge

1. Finn den minste komponenten som avviker.
2. Sjekk etter endrede verdier som datoer, tilfeldige tall, lokalformatering og data hentet to ganger.
3. Fjern nettleseravhengige API-er fra den første serverkompatible gjengivelsen.
4. Sørg for at serveren og den første klientgjengivelsen bruker samme dataøyeblikksbilde.
5. Valider HTML-strukturen.
6. Utelukk utvidelser, CSS-in-JS SSR-konfigurasjon og CDN/Edge-omskriving.
7. Bruk en Effect, målrettet klientavhengig gjengivelse eller React 19.3 use(browser()) kun når innholdet genuint avhenger av nettleseren.
8. Reserver suppressHydrationWarning for små, tilsiktede avvik.
9. Verifiser med en ny omlasting og en produksjonsbygging.

Den varige fiksen er ikke "få React til å slutte å klage". Det er å gjøre den innledende gjengivelseskontrakten eksplisitt: serveren og nettleseren bør være enige om det første brukergrensesnittet, eller den nettleseravhengige seksjonen bør være bevisst isolert slik at React ikke blir bedt om å hydrere markup som aldri kunne samsvart.