¿Qué es el Error 'Hydration Failed' en React y Next.js?
El error de hidratación (Hydration Failed o Text content does not match server-rendered HTML) ocurre típicamente en frameworks de renderizado del lado del servidor (SSR) como Next.js. Sucede cuando el HTML generado estáticamente o en el servidor no coincide exactamente con el primer renderizado que realiza el navegador del cliente al cargar la página.
Causas Principales del Error de Hidratación
Las causas más comunes detrás de este fallo en aplicaciones web modernas incluyen:
- Uso de funciones que cambian según el entorno o el tiempo, como
new Date(),Math.random(), olocalStoragedirectamente en el componente inicial. - Diferencias en las extensiones del navegador que modifican el DOM antes de que React tome el control.
- Etiquetas HTML mal anidadas (por ejemplo, un elemento
<p>dentro de otro<p>o un<div>dentro de un<p>).
Método 1: Utilizar un estado booleano para renderizado condicional en el cliente
La forma más limpia de evitar discrepancias con fechas o valores aleatorios es asegurarse de que el código dependiente del cliente solo se ejecute tras el montaje del componente.
- Importa
useStateyuseEffectdesde 'react'. - Crea un estado booleano
isMountedinicializado enfalse. - Actualiza el estado a
truedentro de un hookuseEffect. - Renderiza condicionalmente el contenido dinámico solo si
isMountedes verdadero.
Ejemplo de código:
const [isMounted, setIsMounted] = useState(false); useEffect(() => { setIsMounted(true); }, []); if (!isMounted) return null; return <div>{new Date().toLocaleTimeString()}</div>;Método 2: Corregir el anidamiento incorrecto de etiquetas HTML
El navegador corrige automáticamente errores estructurales en el HTML antes de que React pueda hidratarlo, lo que genera discrepancias inmediatas.
- Revisa la consola del navegador para identificar qué nodo exacto causó la diferencia.
- Verifica que no estés colocando bloques de tipo bloque (como
<div>o<p>) dentro de elementos que no los admiten según la especificación W3C. - Reemplaza etiquetas problemáticas como
<p>por<span>o<div>si contienen elementos complejos en su interior.
Método 3: Desactivar la hidratación en componentes específicos (Suppress Hydration Warning)
Si estás seguro de que la discrepancia es inofensiva (por ejemplo, atributos inyectados por extensiones del navegador o marcas de tiempo irrelevantes), puedes indicarle a React que ignore la advertencia en un elemento específico.
Añade la propiedad suppressHydrationWarning al elemento HTML afectado:
<div suppressHydrationWarning={true}>{currentTime}</div>Utiliza este método con precaución, ya que solo oculta el síntoma y no resuelve problemas graves de estructura o lógica de renderizado.