Error Handling

Error Handling

Handling errors

Nuxt 3 is a full-stack framework, which means there are several sources of unpreventable user runtime errors that can happen in different contexts:

Errors during the Vue rendering lifecycle (SSR + SPA)
Errors during API or Nitro server lifecycle
Server and client startup errors (SSR + SPA)

Errors during the Vue rendering lifecycle (SSR + SPA)

You can hook into Vue errors using onErrorCaptured.

In addition, Nuxt provides a vue:error hook that will be called if any errors propagate up to the top level.

If you are using a error reporting framework, you can provide a global handler through vueApp.config.errorHandler. It will receive all Vue errors, even if they are handled.

Example with global error reporting framework

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, context) => {
    // ...
  }
})

Server and client startup errors (SSR + SPA)

Nuxt will call the app:error hook if there are any errors in starting your Nuxt application.

This includes:

running Nuxt plugins
processing app:created and app:beforeMount hooks
mounting the app (on client-side), though you should handle this case with onErrorCaptured or with vue:error
processing the app:mounted hook

Errors during API or Nitro server lifecycle

You cannot currently define a server-side handler for these errors, but can render an error page (see the next section).

When Nuxt encounters a fatal error, whether during the server lifecycle, or when rendering your Vue application (both SSR and SPA), it will either render a JSON response (if requested with Accept: application/json header) or an HTML error page.

You can customize this error page by adding ~/error.vue in the source directory of your application, alongside app.vue. This page has a single prop - error which contains an error for you to handle.

When you are ready to remove the error page, you can call the clearError helper function, which takes an optional path to redirect to (for example, if you want to navigate to a ‘safe’ page).

Make sure to check before using anything dependent on Nuxt plugins, such as $route or useRouter, as if a plugin threw an error, then it won’t be re-run until you clear the error.

Example

error.vue

<template>
  <button @click="handleError">Clear errors</button>
</template>
<script setup>
const props = defineProps({
  error: Object
})
const handleError = () => clearError({ redirect: '/' })
</script>

Error helper methods

useError

function useError (): Ref<any>

This function will return the global Nuxt error that is being handled.

👉

Read more in API > Composables > Use Error.

throwError

function throwError (err: string | Error): Error

You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or setup() functions. It will trigger a full-screen error page (as above) which you can clear with clearError.

👉

clearError

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

This function will clear the currently handled Nuxt error. It also takes an optional path to redirect to (for example, if you want to navigate to a ‘safe’ page).

👉

Rendering errors within your app

Nuxt also provides a <NuxtErrorBoundary> component that allows you to handle client-side errors within your app, without replacing your entire site with an error page.

This component is responsible for handling errors that occur within its default slot. On client-side, it will prevent the error from bubbling up to the top level, and will render the #error slot instead.

The #error slot will receive error as a prop. (If you set error = null it will trigger re-rendering the default slot; you’ll need to ensure that the error is fully resolved first or the error slot will just be rendered a second time.)

If you navigate to another route, the error will be cleared automatically.

Example

pages/index.vue

<template>
  <!-- some content -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- You use the default slot to render your content -->
    <template #error="{ error }">
      You can display the error locally here.
      <button @click="error = null">
        This will clear the error.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>

🔎

Read and edit a live example in Examples > App > Error Handling