Как работает обработка ошибок в SvelteKit (+error.svelte, error() из @sveltejs/kit)?

Обработка ошибок в SvelteKit

SvelteKit различает два типа ошибок: ожидаемые (expected) — созданные вручную через error() из @sveltejs/kit, и неожиданные (unexpected) — любые другие исключения. Для их отображения используется файл +error.svelte.

Функция error() из @sveltejs/kit

error(status, message) выбрасывает специальный объект, который SvelteKit перехватывает и отображает через ближайший +error.svelte. Это не обычная ошибка JavaScript — её не нужно оборачивать в try/catch.

// src/routes/posts/[id]/+page.server.ts
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ params }) => {
  const post = await db.posts.findById(params.id);

  if (!post) {
    throw error(404, { message: 'Post not found' });
  }

  if (!post.isPublished) {
    throw error(403, { message: 'Access denied' });
  }

  return { post };
};

Файл +error.svelte

Отображается вместо +page.svelte при ошибке. Доступ к данным ошибки — через $page.error и $page.status:

// src/routes/+error.svelte
<script lang="ts">
  import { page } from '$app/stores';
</script>

<h1>{$page.status}</h1>
<p>{$page.error?.message ?? 'Something went wrong'}</p>

<a href="/">Go home</a>

Иерархия +error.svelte

+error.svelte рендерится внутри ближайшего родительского +layout.svelte. Это позволяет делать разные страницы ошибок для разных секций приложения:

src/routes/
  +error.svelte              # Глобальная страница ошибок
  +layout.svelte
  (admin)/
    +error.svelte            # Ошибки только для /admin/*
    +layout.svelte
    dashboard/
      +page.server.ts

Ошибки в API-маршрутах (+server.ts)

// src/routes/api/users/+server.ts
import { error, json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const GET: RequestHandler = async ({ url }) => {
  const id = url.searchParams.get('id');
  if (!id) {
    throw error(400, 'Missing id parameter');
  }

  const user = await db.users.findById(id);
  if (!user) {
    throw error(404, `User ${id} not found`);
  }

  return json(user);
};

Хук handleError

Для перехвата и логирования неожиданных ошибок используется handleError в hooks.server.ts:

// src/hooks.server.ts
import type { HandleServerError } from '@sveltejs/kit';
import * as Sentry from '@sentry/sveltekit';

export const handleError: HandleServerError = async ({ error, event, status, message }) => {
  // Логируем в Sentry только неожиданные ошибки
  if (status !== 404 && status !== 403) {
    Sentry.captureException(error, { extra: { event } });
  }

  // Возвращаемый объект становится $page.error
  return {
    message: 'An unexpected error occurred',
    errorId: crypto.randomUUID()
  };
};

Клиентский handleError

// src/hooks.client.ts
import type { HandleClientError } from '@sveltejs/kit';

export const handleError: HandleClientError = ({ error, event }) => {
  console.error('Client error:', error);
  return { message: 'Something went wrong on the client' };
};

Подводные камни

• throw error() внутри try/catch будет перехвачен как обычное исключение — никогда не оборачивайте вызов error() в try/catch без явного rethrow.
• Неожиданные ошибки (не через error()) дают статус 500 и НЕ показывают детали пользователю — это безопасно, но требует настройки логирования через handleError.
• +error.svelte не имеет доступа к данным из load сломанной страницы — $page.data будет пустым или частичным.
• Если ошибка происходит в +layout.server.ts, то +error.svelte этого же уровня не сможет помочь — SvelteKit подымается на уровень выше к родительскому layout.
• В handleError нельзя выбрасывать исключения — это вызовет бесконечную рекурсию; оборачивайте тело в try/catch.
• Если второй аргумент error() — строка, $page.error.message будет этой строкой; если объект — он доступен целиком. Тип App.Error в app.d.ts определяет его форму.
• Статус 404 из error() корректно не индексируется поисковиками только при SSR — при SPA-навигации браузер не получает HTTP 404, только JavaScript-состояние.

• Путать SvelteKit errors с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «SvelteKit errors».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.