Cómo solucionar "Text content does not match server-rendered HTML" en Next.js App Router
Este error ocurre cuando el HTML generado por el servidor (SSR/SSG) no coincide con el árbol de React generado durante la primera renderización del cliente. Durante la hidratación, React espera que el DOM inicial coincida exactamente con el que generó el servidor; cualquier diferencia provoca este error crítico.
Causa raíz
La causa más frecuente en aplicaciones modernas es el uso de APIs del navegador (window, localStorage, Date.now(), etc.) directamente en el renderizado, lo que provoca que el contenido sea diferente entre SSR (donde no están disponibles) y CSR (donde sí lo están). Otras causas comunes incluyen:
- Uso de
typeof window !== 'undefined'en el cuerpo del componente (no dentro deuseEffect) - Librerías CSS-in-JS mal configuradas (especialmente
styled-componentssin@emotion/reacto@emotion/server) - Extensiones del navegador (como Dark Reader o ad blockers) que modifican el DOM
- Metaetiquetas de detección automática en iOS (
format-detection) - Minificación automática por CDN (Cloudflare Auto Minify)
Pasos para solucionarlo
✅ Paso 1: Identifica la fuente del desajuste
Busca en tu código:
- Uso de
Date,Math.random(),localStorage,window,navigator, etc. - Lógica condicional basada en
typeof windowfuera de hooks de efecto - Componentes que renderizan contenido dinámico sin protección
🔍 Tip rápido: Usa
console.log('server' if !window else 'client')en el componente sospechoso y revisa el HTML fuente vs. el DOM del navegador.
✅ Paso 2: Aplica la solución según el caso
Caso A: Contenido dinámico (ej. fecha/hora actual, ID aleatorio)
Usa suppressHydrationWarning en el elemento específico:
// ✅ CORRECTO: Solo suprime advertencia en el elemento problemático
<time suppressHydrationWarning>{new Date().toLocaleDateString()}</time>
⚠️ Importante: No lo uses en contenedores grandes (como
<div>que envuelve todo el contenido). Solo en elementos atómicos.
Caso B: Lógica condicional basada en entorno (ej. window o localStorage)
Mueve la lógica a useEffect + estado local:
import { useState, useEffect } from 'react';
export default function ClientOnlyComponent() {
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
// ✅ SSR renderiza siempre el fallback; CSR renderiza lo real tras hidratación
return (
<div>
{isClient ? (
<div>
<p>Contenido del navegador (ej. localStorage: {localStorage.getItem('theme')})</p>
</div>
) : (
<p>Cargando...</p> {/* Contenido idéntico en SSR y CSR inicial */}
)}
</div>
);
}
Caso C: Componente que usa APIs del navegador (ej. window.matchMedia)
Desactiva SSR para ese componente con next/dynamic:
// components/ClientComponent.tsx
export default function ClientComponent() {
const [width, setWidth] = useState(0);
useEffect(() => {
const handleResize = () => setWidth(window.innerWidth);
window.addEventListener('resize', handleResize);
handleResize(); // Inicializar
return () => window.removeEventListener('resize', handleResize);
}, []);
return <p>Ancho: {width}px</p>;
}
// page.tsx
import dynamic from 'next/dynamic';
const ClientComponent = dynamic(() => import('../components/ClientComponent'), {
ssr: false, // ✅ Evita renderizado en servidor
});
export default function Page() {
return (
<main>
<h1>Página principal</h1>
<ClientComponent />
</main>
);
}
Caso D: iOS convierte números/teléfonos en enlaces
Agrega metaetiqueta en <head> (en layout.tsx):
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="es">
<head>
<meta
name="format-detection"
content="telephone=no, date=no, email=no, address=no"
/>
</head>
<body>{children}</body>
</html>
);
}
Caso E: Librerías CSS-in-JS (ej. styled-components)
Configura correctamente para SSR:
npm install @emotion/react @emotion/server
// app/layout.tsx
import { EmotionIntl } from '@emotion/react';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
const cache = createCache({ key: 'css' });
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<head>
<style
data-emotion={`css ${cache.key}`}
dangerouslySetInnerHTML={{ __html: '' }}
/>
</head>
<body>
<CacheProvider value={cache}>{children}</CacheProvider>
</body>
</html>
);
}
🔥 Alternativa recomendada: Usa
@emotion/reactdirectamente ostyled-componentscon su configuración oficial para Next.js.
✅ Paso 3: Verifica configuraciones de CDN
Si usas Cloudflare:
- Desactiva Auto Minify (HTML)
- Desactiva Rocket Loader
- Asegúrate de que Brotli no esté corrompiendo el HTML
🛠️ Prueba rápida: Despliega en entorno local sin CDN. Si el error desaparece, el problema está en la infraestructura.
Pro-tip: Diagnóstico profesional
- Revisa el HTML fuente (Ctrl+U) y compáralo con el DOM del navegador (F12 > Elements).
- Usa
console.log('Hydration check:', window ? 'client' : 'server')en el componente sospechoso. - Activa React DevTools Profiler y busca componentes con
hydrateen rojo. - En producción, usa
suppressHydrationWarningsolo como último recurso — nunca como solución principal.
💡 Regla de oro: Si el contenido cambia entre SSR y CSR, debe estar protegido con
useEffectossr: false. El usuario nunca debe ver un "flash" de contenido diferente durante hidratación.
Aplica estos pasos en orden y el error desaparecerá. Si persiste, revisa logs de tu CDN y extensiones del navegador (prueba en modo incógnito).
🚀 ¿Quieres más soluciones técnicas?
Si te sirvió esta ayuda, suscríbete para recibir los errores más comunes de la semana y cómo evitarlos.
👉 Suscríbete aquí
