¿Qué es el error 'Hydration Failed' en React y Next.js?
El error de hidratación ocurre comúnmente en aplicaciones renderizadas en el servidor (SSR) como Next.js o Remix, cuando el HTML generado en el servidor no coincide exactamente con el primer renderizado del lado del cliente en el navegador.
Causas principales del error de hidratación
- Uso de funciones que devuelven valores dinámicos como
new Date(),Math.random()o datos basados enlocalStoragedirectamente en el renderizado inicial. - Alteración del DOM por extensiones del navegador antes de que React tome el control.
- Etiquetas HTML mal anidadas (por ejemplo, un bloque
<p>dentro de otro<p>o un<div>dentro de un<p>).
Método 1: Aislar el renderizado del lado del cliente con useEffect
Si tu componente depende de variables que cambian constantemente entre el servidor y el cliente, debes retrasar su renderizado hasta que el componente esté montado.
- Identifica el componente o la línea que causa la discrepancia.
- Utiliza un estado booleano junto con
useEffectpara asegurarte de renderizar solo en el cliente:
const [isClient, setIsClient] = useState(false); useEffect(() => { setIsClient(true); }, []); if (!isClient) return null; return <div>{window.innerWidth}</div>;Método 2: Corregir errores de sintaxis y anidamiento HTML
Los navegadores corrigen automáticamente el HTML mal formado al cargarlo, lo que provoca que el DOM del cliente difiera del árbol de elementos virtual de React.
- Revisa la consola del navegador para ver el desglose exacto de la diferencia (diff).
- Sustituye elementos de bloque ilegales dentro de etiquetas de texto (como
<div>dentro de<p>) por etiquetas span o fragmentos seguros.
Método 3: Desactivar temporalmente la hidratación (SupressHydrationWarning)
Si estás seguro de que la diferencia es inofensiva (por ejemplo, atributos inyectados por extensiones del navegador), puedes usar el indicador nativo de React:
<div suppressHydrationWarning>{ }