Cómo Solucionar el Error Hydration Failed en Next.js Paso a Paso

¿Qué es el error Hydration Failed en Next.js?

El error Hydration Failed o Text content does not match server-rendered HTML ocurre en aplicaciones de React y Next.js cuando el marcado HTML generado por el servidor (SSR) no coincide exactamente con el primer renderizado ejecutado en el navegador del cliente. Esta discrepancia rompe la sincronización del DOM virtual y genera advertencias críticas en la consola.

Principales causas del error de hidratación

Identificar la raíz del problema te ahorrará horas de depuración. Las causas más comunes incluyen:

• Uso de funciones que devuelven valores dinámicos diferentes en cada ejecución, como new Date(), Math.random() o localStorage directamente en el renderizado inicial.
• Extensiones del navegador que inyectan atributos o etiquetas HTML en el DOM antes de que React tome el control.
• Anidación incorrecta de etiquetas HTML (por ejemplo, un tag <p> dentro de otro <p> o un <div> dentro de un <p>).

Método 1: Aislar el renderizado del lado del cliente

Si necesitas mostrar datos que solo están disponibles en el navegador (como cookies o dimensiones de la pantalla), debes asegurarte de que el componente solo se renderice después de que el cliente se haya montado.

1. Crea un estado booleano para verificar si el componente está montado: const [isMounted, setIsMounted] = useState(false);
2. Actualiza el estado dentro de un hook useEffect: useEffect(() => { setIsMounted(true); }, []);
3. Condiciona el retorno del componente: if (!isMounted) return null;

Método 2: Usar el atributo suppressHydrationWarning

En ocasiones, herramientas de terceros o extensiones añaden atributos dinámicos (como data-new-gr-c-s-check-loaded) al elemento <body> o contenedores principales, provocando el fallo.

1. Localiza el elemento raíz afectado en tu archivo app/layout.jsx o pages/_app.jsx.
2. Añade el atributo suppressHydrationWarning directamente en la etiqueta JSX:
<html lang="es" suppressHydrationWarning>

Método 3: Corregir la estructura de etiquetas HTML

El navegador corrige automáticamente errores de sintaxis HTML durante el parsing inicial, pero el servidor envía el HTML estricto que escribiste, generando un desfase.

1. Revisa la consola del navegador para identificar el árbol de nodos donde ocurre el conflicto.
2. Sustituye elementos incorrectos, asegurándote de no colocar etiquetas de bloque (como <div> o <p>) dentro de etiquetas en línea (como <span> o <p>).
3. Vuelve a compilar tu aplicación ejecutando npm run build para comprobar que el error ha desaparecido por completo.