Manejo de Errores

La convención de archivo error.js permite manejar errores inesperados en tiempo de ejecución de manera elegante en rutas anidadas.

• Envuelve automáticamente un segmento de ruta y sus hijos en un Límite de Error (Error Boundary) de React.
• Crea interfaces de usuario de error específicas para segmentos usando la jerarquía del sistema de archivos para ajustar la granularidad.
• Aísla errores a los segmentos afectados mientras mantiene funcional el resto de la aplicación.
• Añade funcionalidad para intentar recuperarse de un error sin recargar la página completa.

Crea una interfaz de error añadiendo un archivo error.js dentro de un segmento de ruta y exportando un componente de React:

'use client' // Los componentes de error deben ser Componentes de Cliente

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Registra el error en un servicio de reporte de errores
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>¡Algo salió mal!</h2>
      <button
        onClick={
          // Intenta recuperarse re-renderizando el segmento
          () => reset()
        }
      >
        Intentar nuevamente
      </button>
    </div>
  )
}

'use client' // Los componentes de error deben ser Componentes de Cliente

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // Registra el error en un servicio de reporte de errores
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>¡Algo salió mal!</h2>
      <button
        onClick={
          // Intenta recuperarse re-renderizando el segmento
          () => reset()
        }
      >
        Intentar nuevamente
      </button>
    </div>
  )
}

Cómo funciona error.js

• error.js crea automáticamente un Límite de Error (Error Boundary) de React que envuelve un segmento hijo anidado o el componente page.js.
• El componente React exportado desde error.js se usa como componente alternativo (fallback).
• Si se lanza un error dentro del límite de error, este es contenido y se renderiza el componente alternativo.
• Cuando el componente de error alternativo está activo, los diseños (layouts) superiores al límite de error mantienen su estado y permanecen interactivos, y el componente de error puede mostrar funcionalidad para recuperarse del error.

Recuperación de Errores

A veces la causa de un error puede ser temporal. En estos casos, simplemente intentarlo nuevamente podría resolver el problema.

Un componente de error puede usar la función reset() para permitir al usuario intentar recuperarse del error. Cuando se ejecuta, la función intentará volver a renderizar el contenido del límite de error. Si tiene éxito, el componente de error alternativo será reemplazado por el resultado del nuevo renderizado.

'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>¡Algo salió mal!</h2>
      <button onClick={() => reset()}>Intentar nuevamente</button>
    </div>
  )
}

'use client'

export default function Error({ error, reset }) {
  return (
    <div>
      <h2>¡Algo salió mal!</h2>
      <button onClick={() => reset()}>Intentar nuevamente</button>
    </div>
  )
}

Rutas Anidadas

Los componentes React creados a través de archivos especiales se renderizan en una jerarquía anidada específica.

Por ejemplo, una ruta anidada con dos segmentos que incluyen archivos layout.js y error.js se renderiza en la siguiente jerarquía de componentes simplificada:

La jerarquía de componentes anidados tiene implicaciones para el comportamiento de los archivos error.js en una ruta anidada:

• Los errores suben al límite de error padre más cercano. Esto significa que un archivo error.js manejará errores para todos sus segmentos hijos anidados. Se puede lograr una interfaz de usuario de error más o menos granular colocando archivos error.js en diferentes niveles de las carpetas anidadas de una ruta.
• Un límite error.js no manejará errores lanzados en un componente layout.js del mismo segmento porque el límite de error está anidado dentro del componente de ese diseño.

Manejo de Errores en Diseños (Layouts)

Los límites error.js no capturan errores lanzados en componentes layout.js o template.js del mismo segmento. Esta jerarquía intencional mantiene visible y funcional la interfaz de usuario compartida entre rutas hermanas (como navegación) cuando ocurre un error.

Para manejar errores dentro de un diseño o plantilla específica, coloca un archivo error.js en el segmento padre del diseño.

Para manejar errores dentro del diseño o plantilla raíz, usa una variación de error.js llamada global-error.js.

Manejo de Errores en Diseños Raíz

El límite app/error.js raíz no captura errores lanzados en el componente app/layout.js o app/template.js raíz.

Para manejar específicamente errores en estos componentes raíz, usa una variación de error.js llamada app/global-error.js ubicada en el directorio raíz app.

A diferencia del error.js raíz, el límite de error global-error.js envuelve toda la aplicación, y su componente alternativo reemplaza el diseño raíz cuando está activo. Por esto, es importante notar que global-error.js debe definir sus propias etiquetas <html> y <body>.

global-error.js es la interfaz de usuario de error menos granular y puede considerarse el manejo de errores "general" para toda la aplicación. Es poco probable que se active frecuentemente ya que los componentes raíz son típicamente menos dinámicos, y otros límites error.js capturarán la mayoría de errores.

Incluso si se define un global-error.js, aún se recomienda definir un error.js raíz cuyo componente alternativo se renderizará dentro del diseño raíz, que incluye interfaz de usuario y marca compartida globalmente.

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>¡Algo salió mal!</h2>
        <button onClick={() => reset()}>Intentar nuevamente</button>
      </body>
    </html>
  )
}

'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>¡Algo salió mal!</h2>
        <button onClick={() => reset()}>Intentar nuevamente</button>
      </body>
    </html>
  )
}

Nota importante:

• global-error.js solo está activo en producción. En desarrollo, se mostrará nuestro superposición de errores (error overlay) en su lugar.

Manejo de Errores del Servidor

Si se lanza un error dentro de un Componente de Servidor, Next.js enviará un objeto Error (sin información sensible del error en producción) al archivo error.js más cercano como prop error.

Protección de Información Sensible de Errores

Durante producción, el objeto Error enviado al cliente solo incluye una propiedad genérica message y digest.

Esta es una precaución de seguridad para evitar filtrar detalles potencialmente sensibles incluidos en el error al cliente.

La propiedad message contiene un mensaje genérico sobre el error y la propiedad digest contiene un hash generado automáticamente del error que puede usarse para coincidir con el error correspondiente en los registros del servidor.

Durante desarrollo, el objeto Error enviado al cliente estará serializado e incluirá el message del error original para facilitar la depuración.