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>
  )
}

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 componente error.

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á el message 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>
  )
}

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>
  )
}

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

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`.

Manejo de errores

Aprenda a mostrar errores esperados y manejar excepciones no capturadas.

Manejo de errores

On this page