<NuxtErrorBoundary>

The <NuxtErrorBoundary> component handles errors happening in its default slot, on the server and on the client.
The <NuxtErrorBoundary> uses Vue's onErrorCaptured hook under the hood.

When content in the default slot throws, the #error slot is rendered in its place. This works during server-side rendering as well as on the client: a server-side error results in the #error slot being part of the HTML response (with a 200 status), and the error is passed to the client so that it hydrates into the same state. Calling clearBoundaryError on the client then re-renders the default slot.

In production, a server-side error that is not an HTTP error (such as one created with createError) reaches the #error slot as a generic 500 error, so its message and data are not sent to the browser. HTTP errors keep their status, message and data.

Server-side catching is controlled by the experimental.ssrErrorBoundary option, which is enabled by default. When disabled, the boundary only catches client-side errors.
The boundary catches everything thrown while rendering its default slot, including errors created with fatal: true. It does not intercept errors that bypass the component tree, such as calls to showError, errors thrown in route middleware, or useFetch/useAsyncData failures (which are returned in error rather than thrown). A default slot rendered by a vapor component is only caught on the client.

Props

  • retryOnClient: When the error was caught during server-side rendering, re-render the default slot on the client once mounted. Use this for content that only fails on the server (for example, a component that accesses window): the #error slot is served in the HTML, then replaced by the real content in the browser. If the default slot throws on the client as well, the #error slot is rendered again with the client-side error.

    • type: boolean
    • default: false
    app/pages/example.vue
    <template>
      <NuxtErrorBoundary retry-on-client>
        <BrokeInSSR />
        <template #error>
          <p>Loading…</p>
        </template>
      </NuxtErrorBoundary>
    </template>

Events

  • @error: Event emitted when the default slot of the component throws an error. For an error caught during server-side rendering, it is emitted on the server only.

    app/app.vue
    <template>
      <NuxtErrorBoundary @error="logSomeError">
        <!-- ... -->
      </NuxtErrorBoundary>
    </template>

Slots

  • #error: Specify a fallback content to display in case of error.

    app/app.vue
    <template>
      <NuxtErrorBoundary>
        <!-- ... -->
        <template #error="{ error, clearBoundaryError }">
          <p>An error occurred: {{ error }}</p>
    
          <button @click="clearBoundaryError">
            Clear error
          </button>
        </template>
      </NuxtErrorBoundary>
    </template>
    The slot also exposes clearError as a deprecated alias of clearBoundaryError. Use clearBoundaryError: if a template does not destructure clearError from the slot props, it calls the auto-imported clearError instead, which clears the global error.
Read more in Docs > Getting Started > Error Handling.

Example

Accessing error and clearBoundaryError in Script

You can access error and clearBoundaryError properties within the component's script as below:

app/app.vue
<template>
  <NuxtErrorBoundary ref="errorBoundary">
    <!-- ... -->
  </NuxtErrorBoundary>
</template>

<script setup lang="ts">
const errorBoundary = useTemplateRef('errorBoundary')

// errorBoundary.value?.error
// errorBoundary.value?.clearBoundaryError()
</script>