composables: error handling

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

useError composable return type

The useError() composable returns a Ref containing either an Error object or an object with properties: url, status, statusText, message, description, and data. This represents the global Nuxt error currently being handled.

createError utility function signature

The createError function creates an error object with additional metadata. It accepts either a string (set as error message) or an object containing properties: cause, data, message, name, stack, status, statusText, and fatal. It returns an Error object and is meant to be thrown.

createError behavior on server vs client

When an error created with createError is thrown on the server-side, it triggers a full-screen error page that can be cleared with clearError. On the client-side, it throws a non-fatal error. To trigger a full-screen error page on client-side, set the fatal property to true.

createError cause property in development vs production

In development, the error cause property is preserved and exposed to the error page for tracing the original error. In production, causes are never included in error responses or the error page payload.

createError statusText property requirements

The statusText property should contain only HTTP-compliant status texts (e.g., 'Not Found') with only horizontal tabs, spaces, and visible ASCII characters matching the pattern [\t\u0020-\u007E]. For detailed descriptions, multi-line messages, or non-ASCII content, use the message property instead.

showError utility function signature

The showError function accepts either a string, an Error object, or an object with properties: status and statusText. It can be called at any point on client-side or on server-side directly within middleware, plugins, or setup() functions, and triggers a full-screen error page that can be cleared with clearError.

clearError utility function signature

The clearError function has the signature: function clearError(options?: { redirect?: string }): Promise<void>. It clears the currently handled Nuxt error and optionally redirects to a specified path.

vue:error hook

The vue:error hook is a Nuxt runtime hook that is called if any errors propagate up to the top level during the Vue rendering lifecycle. It is based on the onErrorCaptured Vue lifecycle hook.

app:error hook

The app:error hook is called if there are any errors during Nuxt application startup. This includes errors while running Nuxt plugins, processing app:created and app:beforeMount hooks, rendering the Vue app to HTML during SSR, mounting the app on client-side, and processing the app:mounted hook.

Chunk loading errors behavior

Nuxt provides built-in support for handling chunk loading errors by performing a hard reload when a chunk fails to load during route navigation. The behavior can be changed by setting experimental.emitRouteChunkError to false (to disable hooking into errors) or to 'manual' if you want to handle them yourself.

vueApp.config.errorHandler global handler

A global error handler can be provided through vueApp.config.errorHandler in a Nuxt plugin. It receives all Vue errors, even if they are handled. The handler signature is (error, instance, info) where error is the error object, instance is the Vue component instance, and info is a Vue-specific error string.

createError example usage

Example: throw createError({ status: 404, statusText: 'Page Not Found' }) in a page to trigger a 404 error page when data is not found after fetching.

Give your agent this brain