error.js
Un archivo error le permite manejar errores inesperados en tiempo de ejecución y mostrar una interfaz de usuario alternativa.

'use client' // Los límites de error deben ser Componentes de Cliente
import { useEffect } from 'react'
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
useEffect(() => {
// Registrar el error en un servicio de reporte de errores
console.error(error)
}, [error])
return (
<div>
<h2>¡Algo salió mal!</h2>
<button
onClick={
// Intentar recuperarse re-renderizando el segmento
() => reset()
}
>
Reintentar
</button>
</div>
)
}
'use client' // Los límites de error deben ser Componentes de Cliente
import { useEffect } from 'react'
export default function Error({ error, reset }) {
useEffect(() => {
// Registrar el error en un servicio de reporte de errores
console.error(error)
}, [error])
return (
<div>
<h2>¡Algo salió mal!</h2>
<button
onClick={
// Intentar recuperarse re-renderizando el segmento
() => reset()
}
>
Reintentar
</button>
</div>
)
}
error.js
envuelve un segmento de ruta y sus hijos anidados en un Límite de Error de React. Cuando se lanza un error dentro del límite, el componente error
se muestra como interfaz de usuario alternativa.

Importante:
- Las Herramientas de Desarrollo de React permiten alternar límites de error para probar estados de error.
- Si desea que los errores se propaguen al límite de error padre, puede usar
throw
al renderizar el componenteerror
.
Referencia
Props
error
Una instancia de un objeto Error
enviado al Componente de Cliente error.js
.
Importante: Durante el desarrollo, el objeto
Error
enviado al cliente será serializado e incluirá elmessage
del error original para facilitar la depuración. Sin embargo, este comportamiento es diferente en producción para evitar filtrar detalles potencialmente sensibles incluidos en el error al cliente.
error.message
- Los errores provenientes de Componentes de Cliente muestran el mensaje original del
Error
. - Los errores provenientes de Componentes de Servidor muestran un mensaje genérico con un identificador. Esto evita filtrar detalles sensibles. Puede usar el identificador, bajo
errors.digest
, para coincidir con los registros correspondientes del lado del servidor.
error.digest
Un hash generado automáticamente del error lanzado. Puede usarse para coincidir con el error correspondiente en los registros del servidor.
reset
La causa de un error a veces puede ser temporal. En estos casos, intentar nuevamente podría resolver el problema.
Un componente de error puede usar la función reset()
para solicitar al usuario que intente recuperarse del error. Cuando se ejecuta, la función intentará re-renderizar el contenido del límite de error. Si tiene éxito, el componente de error alternativo se reemplaza con el resultado del re-renderizado.
'use client' // Los límites de error deben ser Componentes de Cliente
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div>
<h2>¡Algo salió mal!</h2>
<button onClick={() => reset()}>Reintentar</button>
</div>
)
}
'use client' // Los límites de error deben ser Componentes de Cliente
export default function Error({ error, reset }) {
return (
<div>
<h2>¡Algo salió mal!</h2>
<button onClick={() => reset()}>Reintentar</button>
</div>
)
}
Ejemplos
Error Global
Aunque menos común, puede manejar errores en el diseño raíz o plantilla usando global-error.js
, ubicado en el directorio raíz de la aplicación, incluso cuando se utiliza internacionalización. La interfaz de error global debe definir sus propias etiquetas <html>
y <body>
. Este archivo reemplaza el diseño raíz o plantilla cuando está activo.
'use client' // Los límites de error deben ser Componentes de Cliente
export default function GlobalError({
error,
reset,
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
// global-error debe incluir etiquetas html y body
<html>
<body>
<h2>¡Algo salió mal!</h2>
<button onClick={() => reset()}>Reintentar</button>
</body>
</html>
)
}
'use client' // Los límites de error deben ser Componentes de Cliente
export default function GlobalError({ error, reset }) {
return (
// global-error debe incluir etiquetas html y body
<html>
<body>
<h2>¡Algo salió mal!</h2>
<button onClick={() => reset()}>Reintentar</button>
</body>
</html>
)
}
Recuperación elegante de errores con un límite de error personalizado
Cuando falla el renderizado en el cliente, puede ser útil mostrar la última interfaz renderizada por el servidor conocida para una mejor experiencia de usuario.
El GracefullyDegradingErrorBoundary
es un ejemplo de un límite de error personalizado que captura y preserva el HTML actual antes de que ocurra un error. Si ocurre un error de renderizado, re-renderiza el HTML capturado y muestra una barra de notificación persistente para informar al usuario.
'use client'
import React, { Component, ErrorInfo, ReactNode } from 'react'
interface ErrorBoundaryProps {
children: ReactNode
onError?: (error: Error, errorInfo: ErrorInfo) => void
}
interface ErrorBoundaryState {
hasError: boolean
}
export class GracefullyDegradingErrorBoundary extends Component<
ErrorBoundaryProps,
ErrorBoundaryState
> {
private contentRef: React.RefObject<HTMLDivElement>
constructor(props: ErrorBoundaryProps) {
super(props)
this.state = { hasError: false }
this.contentRef = React.createRef()
}
static getDerivedStateFromError(_: Error): ErrorBoundaryState {
return { hasError: true }
}
componentDidCatch(error: Error, errorInfo: ErrorInfo) {
if (this.props.onError) {
this.props.onError(error, errorInfo)
}
}
render() {
if (this.state.hasError) {
// Renderizar el contenido HTML actual sin hidratación
return (
<>
<div
ref={this.contentRef}
suppressHydrationWarning
dangerouslySetInnerHTML={{
__html: this.contentRef.current?.innerHTML || '',
}}
/>
<div className="fixed bottom-0 left-0 right-0 bg-red-600 text-white py-4 px-6 text-center">
<p className="font-semibold">
Ocurrió un error durante el renderizado de la página
</p>
</div>
</>
)
}
return <div ref={this.contentRef}>{this.props.children}</div>
}
}
export default GracefullyDegradingErrorBoundary
'use client'
import React, { Component, createRef } from 'react'
class GracefullyDegradingErrorBoundary extends Component {
constructor(props) {
super(props)
this.state = { hasError: false }
this.contentRef = createRef()
}
static getDerivedStateFromError(_) {
return { hasError: true }
}
componentDidCatch(error, errorInfo) {
if (this.props.onError) {
this.props.onError(error, errorInfo)
}
}
render() {
if (this.state.hasError) {
// Renderizar el contenido HTML actual sin hidratación
return (
<>
<div
ref={this.contentRef}
suppressHydrationWarning
dangerouslySetInnerHTML={{
__html: this.contentRef.current?.innerHTML || '',
}}
/>
<div className="fixed bottom-0 left-0 right-0 bg-red-600 text-white py-4 px-6 text-center">
<p className="font-semibold">
Ocurrió un error durante el renderizado de la página
</p>
</div>
</>
)
}
return <div ref={this.contentRef}>{this.props.children}</div>
}
}
export default GracefullyDegradingErrorBoundary
Historial de Versiones
Versión | Cambios |
---|---|
v15.2.0 | También muestra global-error en desarrollo. |
v13.1.0 | Se introduce global-error . |
v13.0.0 | Se introduce error . |