Nuxt es un framework full-stack, lo que significa que hay varias fuentes de errores de ejecución del usuario que no se pueden prevenir y que pueden ocurrir en diferentes contextos:

• Errores durante el ciclo de vida de renderizado de Vue (SSR & CSR)
• Errores de inicio del servidor y del cliente (SSR + CSR)
• Errores durante el ciclo de vida del servidor Nitro (directorio server/)
• Errores al descargar fragmentos de JS

Errores de Vue

Puedes engancharte a los errores de Vue usando onErrorCaptured.

Además, Nuxt proporciona un hook vue:error que se llamará si algún error se propaga hasta el nivel superior.

Si estás utilizando un framework de reporte de errores, puedes proporcionar un manejador global a través de vueApp.config.errorHandler. Recibirá todos los errores de Vue, incluso si son manejados.

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    // manejar el error, por ejemplo, reportar a un servicio
  }

  // También es posible
  nuxtApp.hook('vue:error', (error, instance, info) => {
    // manejar el error, por ejemplo, reportar a un servicio
  })
})

Errores de Inicio

Nuxt llamará al hook app:error si hay algún error al iniciar tu aplicación Nuxt.

Esto incluye:

• ejecutar plugins de Nuxt
• procesar los hooks app:created y app:beforeMount
• renderizar tu aplicación Vue a HTML (durante SSR)
• montar la aplicación (en el lado del cliente), aunque deberías manejar este caso con onErrorCaptured o con vue:error
• procesar el hook app:mounted

Errores del Servidor Nitro

Actualmente no puedes definir un manejador del lado del servidor para estos errores, pero puedes renderizar una página de error, consulta la sección Renderizar una Página de Error.

Errores con Fragmentos de JS

Podrías encontrar errores de carga de fragmentos debido a una falla de conectividad de red o un nuevo despliegue (que invalida tus antiguas URLs de fragmentos de JS con hash). Nuxt proporciona soporte incorporado para manejar errores de carga de fragmentos realizando una recarga completa cuando un fragmento falla al cargar durante la navegación de rutas.

Puedes cambiar este comportamiento configurando experimental.emitRouteChunkError a false (para deshabilitar el enganche a estos errores por completo) o a manual si deseas manejarlos tú mismo. Si deseas manejar los errores de carga de fragmentos manualmente, puedes consultar la implementación automática para obtener ideas.

Página de Error

Un error puede ocurrir durante el ciclo de vida del servidor cuando:

• se procesan tus plugins de Nuxt
• se renderiza tu aplicación Vue en HTML
• una ruta API del servidor lanza un error

También puede ocurrir en el lado del cliente cuando:

• se procesan tus plugins de Nuxt
• antes de montar la aplicación (hook app:beforeMount)
• al montar tu aplicación si el error no fue manejado con el hook onErrorCaptured o vue:error
• la aplicación Vue está inicializada y montada en el navegador (app:mounted).

Personaliza la página de error predeterminada agregando ~/error.vue en el directorio fuente de tu aplicación, junto a app.vue.

<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps({
  error: Object as () => NuxtError
})

const handleError = () => clearError({ redirect: '/' })
</script>

<template>
  <div>
    <h2>{{ error?.statusCode }}</h2>
    <button @click="handleError">Limpiar errores</button>
  </div>
</template>

Para errores personalizados recomendamos encarecidamente usar el composable onErrorCaptured que puede ser llamado en una función de configuración de página/componente o el hook de tiempo de ejecución vue:error de Nuxt que puede ser configurado en un plugin de Nuxt.

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.hook('vue:error', (err) => {
    //
  })
})

Cuando estés listo para eliminar la página de error, puedes llamar a la función auxiliar clearError, que toma una ruta opcional a la que redirigir (por ejemplo, si deseas navegar a una página 'segura').

Utilidades de Error

useError

function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>

Esta función devolverá el error global de Nuxt que se está manejando.

createError

function createError (err: string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error

Crea un objeto de error con metadatos adicionales. Puedes pasar una cadena para establecer como el message del error o un objeto que contenga propiedades de error. Es utilizable tanto en las partes de Vue como del Servidor de tu aplicación, y está destinado a ser lanzado.

Si lanzas un error creado con createError:

• en el lado del servidor, activará una página de error a pantalla completa que puedes limpiar con clearError.
• en el lado del cliente, lanzará un error no fatal para que lo manejes. Si necesitas activar una página de error a pantalla completa, entonces puedes hacerlo configurando fatal: true.

const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)

if (!data.value) {
  throw createError({
    statusCode: 404,
    statusMessage: 'Página No Encontrada'
  })
}

showError

function showError (err: string | Error | { statusCode, statusMessage }): Error

Puedes llamar a esta función en cualquier momento en el lado del cliente, o (en el lado del servidor) directamente dentro de middleware, plugins o funciones setup(). Activará una página de error a pantalla completa que puedes limpiar con clearError.

Se recomienda en su lugar usar throw createError().

clearError

function clearError (options?: { redirect?: string }): Promise<void>

Esta función limpiará el error de Nuxt que se está manejando actualmente. También toma una ruta opcional a la que redirigir (por ejemplo, si deseas navegar a una página 'segura').

Renderizar Error en Componente

Nuxt también proporciona un componente <NuxtErrorBoundary> que te permite manejar errores del lado del cliente dentro de tu aplicación, sin reemplazar todo tu sitio con una página de error.

Este componente es responsable de manejar errores que ocurren dentro de su slot predeterminado. En el lado del cliente, evitará que el error se propague al nivel superior, y renderizará el slot #error en su lugar.

El slot #error recibirá error como una prop. (Si estableces error = null activará la re-renderización del slot predeterminado; necesitarás asegurarte de que el error esté completamente resuelto primero o el slot de error simplemente se renderizará una segunda vez.)

<template>
  <!-- algún contenido -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- Usas el slot predeterminado para renderizar tu contenido -->
    <template #error="{ error, clearError }">
      Puedes mostrar el error localmente aquí: {{ error }}
      <button @click="clearError">
        Esto limpiará el error.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>