Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Nuxe ships a small but complete error-handling system built around the NuxeError class. createError constructs a structured error from any input, showError throws it while simultaneously updating the app-wide error state (so your error page component reacts), useError reads the current error as a reactive Ref, and clearError resets the state and optionally navigates away.

​
NuxeError

NuxeError extends the native Error class with HTTP-aware fields. It is the canonical error type in Nuxe and is recognized by all error utilities. 
class NuxeError extends Error {
  readonly statusCode: number
  readonly statusMessage: string
  readonly description?: string
  readonly data?: unknown
}
​
statusCode
number
The HTTP status code associated with the error. Defaults to 500 when not specified.
​
statusMessage
string
A short human-readable status phrase (e.g. "Not Found", "Forbidden"). Defaults to "Internal Server Error".
​
message
string
The standard Error.message. Falls back to statusMessage if not provided.
​
description
string | undefined
An optional longer description intended for display on the error page.
​
data
unknown
Any additional structured data you want to attach to the error (e.g. validation errors, original response body).

​
createError

Constructs a NuxeError from a payload object, a plain string, or a native Error.

​
Signature

createError(payload: NuxeErrorPayload | string | Error): NuxeError
​
payload
NuxeErrorPayload | string | Error
required
Accepts three forms:
  • NuxeErrorPayload object — mapped directly to NuxeError fields.
  • string — used as statusMessage; statusCode defaults to 500.
  • Error instance — message is preserved; statusCode defaults to 500.
  • NuxeError instance — returned as-is without wrapping.
The NuxeErrorPayload shape:
​
payload.statusCode
number
HTTP status code. Defaults to 500.
​
payload.statusMessage
string
Short status phrase. Defaults to "Internal Server Error".
​
payload.message
string
The error message. Defaults to statusMessage when omitted.
​
payload.description
string
Longer human-readable description for the error page.
​
payload.data
unknown
Arbitrary structured data to attach to the error.

​
showError

Throws a NuxeError and writes it into the app’s reactive error state so that the error page component updates immediately.

​
Signature

showError(err: NuxeErrorPayload | string | Error): never
showError accepts the same inputs as createError, wraps them in a NuxeError internally, sets the injected error Ref, and then throws. Because it always throws, TypeScript infers the return type as never — you can use it in places that require a definite code path termination.
showError must be called from within a component’s setup() function (or a composable called from setup()) so that it has access to the Vue component instance needed to update the app error state. If called outside a component, the error is still thrown but the reactive error state is not updated.

​
useError

Returns the current app-level error as a reactive Ref.

​
Signature

useError(): Ref<NuxeError | null>
​
(return value)
Ref<NuxeError | null>
A Ref that is null when no error is active and holds the current NuxeError when one has been set via showError. Use this in your error page component to display error details.

​
clearError

Resets the app-level error state. Optionally navigates the user to a different route after clearing.

​
Signature

clearError(options?: { redirect?: string }): void
​
options.redirect
string
A route path to navigate to after the error is cleared. If omitted, the current route is kept.

​
isNuxeError

A type guard that returns true if the given value is a NuxeError instance (or a structurally compatible plain object with name === 'NuxeError' and a numeric statusCode).

​
Signature

isNuxeError(err: unknown): err is NuxeError

​
serializeError / deserializeError

Utilities for converting NuxeError instances to and from plain objects during SSR payload serialization. 
serializeError(err: unknown): NuxeErrorPayload | null
deserializeError(payload: NuxeErrorPayload): NuxeError
serializeError returns null for any value that is not a NuxeError. deserializeError constructs a fresh NuxeError from a plain payload object, restoring the full class prototype chain after JSON deserialization.

​
Examples

​
Throwing a 404 from a page component

<script setup lang="ts">
import { useFetch, createError, showError } from '@dvlkit/nuxe'

const { data: post, error } = await useFetch('/api/posts/999')

if (error.value) {
  throw showError(
    createError({
      statusCode: 404,
      statusMessage: 'Not Found',
      message: 'The requested post does not exist.',
    })
  )
}
</script>

​
Custom error page (error.vue)

<!-- error.vue -->
<script setup lang="ts">
import { useError, clearError } from '@dvlkit/nuxe'

const error = useError()
</script>

<template>
  <main>
    <h1>{{ error?.statusCode }} — {{ error?.statusMessage }}</h1>
    <p>{{ error?.description }}</p>
    <button @click="clearError({ redirect: '/' })">Go home</button>
  </main>
</template>

​
Inline error guard with isNuxeError

import { isNuxeError, createError } from '@dvlkit/nuxe'

async function loadUser(id: string) {
  try {
    return await $fetch(`/api/users/${id}`)
  } catch (err) {
    if (isNuxeError(err) && err.statusCode === 404) {
      throw createError({ statusCode: 404, statusMessage: 'User not found' })
    }
    throw err
  }
}
Use createError to build the error object and then throw it yourself when you do not need to update the reactive app state (e.g. inside a utility function). Only call showError from a component setup context where you want the error page to render.

Build docs developers (and LLMs) love

Get started for freeTalk to us