El error aparece cuando el HTML generado por el servidor no coincide con lo que React produce en el primer render del navegador durante la hidratación. La solución preferible es hacer que ambos generen la misma salida inicial. Empieza por comparar los datos y valores que cambian; después revisa APIs del navegador, fechas y formatos, markup inválido y modificaciones del HTML por extensiones o servicios externos.
Qué significa el error de hidratación
Next.js muestra “Text content does not match server-rendered HTML” cuando React encuentra una diferencia entre el HTML prerenderizado y el árbol que genera el navegador al hidratarlo. Hidratar significa conectar al HTML existente la lógica e interactividad de React; no es un segundo render independiente en el que el contenido inicial pueda variar libremente. React requiere que ambos lados concuerden.
As an Amazon Associate I earn from qualifying purchases.
El mensaje señala una discrepancia, no identifica por sí solo su causa. La documentación oficial de Next.js y la guía de React sobre hydrateRoot describen causas y alternativas generales. Sin el código, la versión instalada y el navegador implicado no se puede atribuir el problema a una causa concreta ni asumir que sea exclusivo de App Router.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Cómo encontrar qué está cambiando
Localiza el primer elemento o texto que difiere y sigue el valor que lo genera. Pregunta qué valor se usó para producir el HTML del servidor y cuál se usó en el primer render del navegador.
#1 Best Overall
- Datos y estado inicial: verifica que el cliente empiece con el mismo conjunto de datos que produjo el HTML. Si cada lado obtiene una respuesta distinta o parte de un estado distinto, su JSX puede no coincidir.
- APIs del navegador: busca lecturas de
window,localStorage,matchMediau otras APIs dentro de la lógica que decide el JSX inicial. Esas APIs no representan necesariamente el mismo valor en el servidor y el navegador. - Tiempo y valores variables: revisa
Date(), horas, números aleatorios y formatos de fecha dependientes de la configuración regional. Un valor calculado en instantes distintos o con locales distintos puede producir texto diferente. - Markup inválido: inspecciona anidaciones incorrectas, como un
<p>dentro de otro<p>, un<div>dentro de un párrafo o controles interactivos anidados, como enlaces o botones. - HTML modificado después de generarse: si ocurre solo en ciertos navegadores o en producción, comprueba si una extensión altera el DOM, si un CDN transforma el HTML —Next.js menciona Cloudflare Auto Minify— o si iOS convierte automáticamente datos de contacto en enlaces.
- CSS-in-JS: comprueba que la biblioteca y su configuración de renderizado en servidor sigan el ejemplo oficial correspondiente. Una configuración incorrecta también puede causar discrepancias.
Arreglos posibles y cuándo usarlos
| Estrategia | Cuándo encaja | Efecto o límite |
|---|---|---|
| Hacer idéntico el render inicial | Los datos, el estado o el formato pueden mantenerse estables. | Resuelve la discrepancia en su origen y cumple el requisito de concordancia de React. |
Actualizar con useEffect |
La variante necesita información del navegador después de la hidratación. | Provoca un render posterior; el cambio puede notarse y la pasada adicional puede ralentizar la hidratación. |
dynamic(..., { ssr: false }) |
Un componente específico solo puede renderizarse en el navegador. | Desactiva el prerenderizado para ese componente; no es una solución general para toda la página. |
suppressHydrationWarning |
Una diferencia inevitable afecta a un elemento concreto. | Silencia el aviso en un nivel; no corrige el contenido discrepante. |
1. Haz determinista la salida inicial
Es la primera opción cuando puedes controlar los datos o el formato. Usa en el navegador el mismo snapshot de datos y estado inicial que corresponde al HTML ya generado. Evita consultar APIs del navegador para decidir qué contenido incluir en el primer JSX, y no calcules ese contenido a partir de la hora actual, un número aleatorio o un formato regional que pueda variar entre entornos.
2. Pasa la variante de navegador a un efecto
Si el contenido depende necesariamente del navegador, representa inicialmente un valor común y actualízalo en useEffect después de la hidratación. Next.js documenta esta técnica para evitar que una API del navegador cambie el primer render. Como se muestra una segunda salida, el cambio puede ser perceptible.
Rank #2
'use client'
import { useEffect, useState } from 'react'
export default function ClientValue() {
const [ready, setReady] = useState(false)
useEffect(() => setReady(true), [])
return <span>{ready ? 'contenido del cliente' : 'contenido inicial estable'}</span>
}El valor inicial debe ser el mismo en servidor y navegador. En App Router, añade 'use client' si el componente utiliza hooks.
3. Desactiva el prerenderizado solo para el componente necesario
Para un widget que no puede renderizarse en servidor, Next.js documenta una importación dinámica con { ssr: false } dentro de un componente de cliente:
'use client'
import dynamic from 'next/dynamic'
const BrowserOnlyWidget = dynamic(() => import('./browser-only-widget'), {
ssr: false,
})Aplica esta excepción con alcance localizado; el ejemplo oficial se refiere a componentes seleccionados, no a desactivar el renderizado en servidor de toda la página como respuesta automática.
4. Reserva la supresión para una diferencia inevitable y puntual
suppressHydrationWarning={true} puede usarse en un elemento cuyo contenido necesariamente difiere, como una marca temporal. Es una salida de emergencia: solo actúa un nivel hacia abajo y React no intenta parchear el texto discrepante bajo esa supresión. No la uses para ocultar una diferencia amplia ni como primer paso de diagnóstico.
5. Desactiva la detección automática de datos de contacto de iOS, si es la causa
Next.js indica que iOS puede transformar números de teléfono, correos y otros datos de texto en enlaces. Si esa modificación causa la discrepancia, la documentación propone esta etiqueta meta:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →<meta name="format-detection" content="telephone=no, date=no, email=no, address=no" />Comprueba el resultado y evita los falsos arreglos
- Corrige primero la fuente de la diferencia que hayas encontrado: datos, estado, formato, estructura del markup o HTML transformado.
- Vuelve a cargar la página en el entorno donde aparece el aviso y confirma que el primer render del navegador concuerda con el HTML del servidor.
- Si el contenido debe variar según el navegador, mueve esa variación a un efecto o limita el renderizado en servidor al componente que no puede prerenderizarse.
- Comprueba cualquier ejemplo contra las versiones de Next.js y React que tengas instaladas. Las fuentes citadas documentan el comportamiento general, pero el caso concreto depende del código y el entorno.
Silenciar el aviso sin eliminar o contener la causa deja sin resolver la diferencia que React encontró. Por eso, usa suppressHydrationWarning solo cuando la discrepancia sea inevitable, localizada y conocida.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
