8000 docs: update rendering error page by mihul87 Β· Pull Request #22523 Β· nuxt/nuxt Β· GitHub
[go: up one dir, main page]

Skip to content

docs: update rendering error page #22523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Aug 9, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions docs/1.getting-started/8.error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,36 @@ You can change this behavior by setting `experimental.emitRouteChunkError` to `f

## Rendering an Error Page

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.
When Nuxt encounters a fatal error (any unhandled error on the server, or an error created with `fatal: true` on the client) it will either render a JSON response (if requested with `Accept: application/json` header) or trigger a full-screen 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.
This error may occur during the server lifecycle when:

* processing your Nuxt plugins
* rendering your Vue app into HTML
* a server API route throws an error

An error can also occur on the client side when:

* processing your Nuxt plugins
* before mounting the application (`app:beforeMount` hook)
* mounting your app if the error was not handled with `onErrorCaptured` or `vue:error` hook
* the Vue app is initialized and mounted in browser (`app:mounted`).

The lifecycle hooks are listed [here](/docs/api/advanced/hooks).

You can customize this error page by adding `~/error.vue` in the source directory of your application, alongside `app.vue`. Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page.

The error page has a single prop - `error` which contains an error for you to handle.

The `error` object provides the fields: `url`, `statusCode`, `statusMessage`, `message`, `description` and `data`. If you have an error with custom fields they will be lost; you should assign them to `data` instead. For custom errors we highly recommend to use `onErrorCaptured` composable that can be called in a page/component setup function or `vue:error` runtime nuxt hook that can be configured in a nuxt plugin.

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

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

Expand Down
0