createError

Source
Создание объекта ошибки с дополнительными метаданными.

Функция создаёт объект ошибки с дополнительными метаданными. Используется и во Vue-части приложения, и в Nitro (API); объект предназначен для выброса через throw.

Параметры

  • err: string | { cause, data, message, name, stack, status, statusText, fatal } — строка или объект. Строка задаёт message, status по умолчанию 500. В объекте можно задать status, message и другие поля ошибки.

Во Vue-приложении

При выбросе ошибки, созданной через createError:

  • на сервере отображается полноэкранная страница ошибки (сброс — clearError);
  • на клиенте выбрасывается некритичная ошибка для обработки. Чтобы показать полноэкранную страницу ошибки на клиенте, передайте fatal: true.

Пример

app/pages/movies/[slug].vue
<script setup lang="ts">
const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)
if (!data.value) {
  throw createError({ status: 404, statusText: 'Страница не найдена' })
}
</script>

Причины ошибок (cause)

При создании ошибки можно передать cause, чтобы сохранить исходную ошибку, которую вы оборачиваете:

try {
  await fetchMovie(route.params.slug)
} catch (cause) {
  throw createError({
    status: 500,
    message: 'Could not load movie',
    cause,
  })
}

В режиме разработки цепочка причин доступна на странице ошибки через свойство cause, сериализованное как { name, message, stack, cause } (примитивные причины передаются как есть; остальные значения опускаются). В production причины никогда не включаются в ответы об ошибках и в payload страницы ошибки.

В API-маршрутах

createError используется для вызова обработки ошибок в серверных API-маршрутах.

Пример

server/api/error.ts
export default eventHandler(() => {
  throw createError({
    status: 404,
    statusText: 'Страница не найдена',
  })
})

В API-маршрутах лучше передавать объект с кратким statusText: он доступен на клиенте. message, переданный в createError в API, на клиент не попадает. Дополнительные данные можно передать через свойство data. При обработке ошибки через useFetch пользовательские данные доступны в error.value.data.data. Не подставляйте в сообщение динамический пользовательский ввод — это может быть небезопасно.

Узнать больше Docs > 4 X > Getting Started > Error Handling.