JavaScript

Qué significa Hydration Failed y cómo solucionarlo

Referencia del error

Hydration Failed

Lenguaje

JavaScript

Severidad

Alta

Cuándo ocurre

El error de hidratación de React 18 ocurre cuando el HTML enviado desde el servidor no coincide con el árbol de componentes que React intenta renderizar en el cliente.

Posibles soluciones

Difiere el contenido dinámico a un useEffect que se ejecuta solo en el cliente. Usa suppressHydrationWarning con moderación para diferencias verdaderamente intencionales (como marcas de tiempo). Mantén el renderizado inicial determinista e idéntico tanto en servidor como en cliente.

Errores relacionados

Invalid Hook Call Too many re-renders useEffect con dependencia faltante

Más detalles

El error de hidratación de React 18 ocurre cuando el HTML enviado desde el servidor no coincide con el árbol de componentes que React intenta renderizar en el cliente. React espera que el renderizado inicial del cliente sea idéntico al renderizado del servidor para poder 'adoptar' los nodos DOM existentes.

Por qué ocurre

•Renderizar valores dinámicos como new Date() o Math.random() que difieren entre servidor y cliente.
•Leer APIs solo del navegador como window o localStorage durante el renderizado inicial.
•Renderizar contenido basado en cookies o estado de autenticación que difiere entre entornos.
•Usar un componente de terceros que no es seguro para SSR.

Posibles soluciones

Difiere el contenido dinámico a un useEffect que se ejecuta solo en el cliente. Usa suppressHydrationWarning con moderación para diferencias verdaderamente intencionales (como marcas de tiempo). Mantén el renderizado inicial determinista e idéntico tanto en servidor como en cliente.

Ejemplos

JavaScript

Código que causa el error

function Timestamp() {
  // Different on server vs client
  return <p>{new Date().toLocaleTimeString()}</p>;
}

Error en la terminal

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

Código corregido

"use client";
import { useEffect, useState } from "react";

function Timestamp() {
  const [time, setTime] = useState<string | null>(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);
  return <p>{time ?? "Loading..."}</p>;
}

Practica en inglés

¿Cómo le explicarías un Hydration Failed a un compañero dev? Elige la frase correcta:

"I hit an error...

¿Listo para practicar tu inglés en el trabajo?

Lingua-e tiene ejercicios interactivos basados en conversaciones reales de developers: standups, code reviews, retrospectivas y más. Practica hasta que salga solo.

Prueba Lingua-e gratis