Error handling

Errors are inevitable in software development. SvelteKit handles errors differently depending on where they occur and what kind they are.

Error objects

SvelteKit distinguishes between expected and unexpected errors, both represented as simple { message: string } objects by default.

You can add additional properties like code or tracking id by customizing the App.Error type.

Expected errors

An expected error is created with the error helper from @sveltejs/kit:

src/routes/blog/[slug]/+page.server.js

import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';

export async function load({ params }) {
	const post = await db.getPost(params.slug);

	if (!post) {
		error(404, {
			message: 'Not found'
		});
	}

	return { post };
}

This causes SvelteKit to:

Set the response status

Sets the HTTP status code to 404

Render error page

Renders the nearest +error.svelte component

Pass error object

Makes the error object available as page.error

Displaying errors

src/routes/+error.svelte

<script>
	import { page } from '$app/state';
</script>

<h1>{page.error.message}</h1>

Adding custom properties

declare global {
	namespace App {
		interface Error {
			message: string;
			code: string;
		}
	}
}

export {};

import { error } from '@sveltejs/kit';

error(404, {
	message: 'Not found',
	code: 'NOT_FOUND'
});

Shorthand syntax

For convenience, pass a string as the second argument:

error(404, 'Not found');

Unexpected errors

An unexpected error is any other exception that occurs while handling a request. These can contain sensitive information, so messages and stack traces are not exposed to users.

By default, unexpected errors are printed to the console but show a generic message to users:

{ "message": "Internal Error" }

handleError hook

Unexpected errors go through the handleError hook, where you can:

Log errors to a service

src/hooks.server.js

import * as Sentry from '@sentry/sveltekit';

Sentry.init({/*...*/})

export async function handleError({ error, event, status, message }) {
  const errorId = crypto.randomUUID();
  
  Sentry.captureException(error, {
    extra: { event, errorId, status }
  });
  
  return {
    message: 'Whoops!',
    errorId
  };
}

Return custom error objects

src/hooks.server.js

export async function handleError({ error, event, status, message }) {
  // Extract safe information
  const errorId = crypto.randomUUID();
  
  return {
    message: 'An error occurred',
    errorId,
    timestamp: new Date().toISOString()
  };
}

Handle client errors

src/hooks.client.js

export async function handleError({ error, event, status, message }) {
  console.error('Client error:', error);
  
  return {
    message: 'Something went wrong',
    code: 'CLIENT_ERROR'
  };
}

Make sure that handleError never throws an error itself.

Error responses

How SvelteKit responds to errors depends on where they occur:

In handle or +server.js

SvelteKit responds with either:

Fallback error page (if Accept header expects HTML)
JSON representation (if Accept header is application/json)

Custom fallback page

Create src/error.html to customize the fallback error page:

src/error.html

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>%sveltekit.error.message%</title>
	</head>
	<body>
		<h1>My custom error page</h1>
		<p>Status: %sveltekit.status%</p>
		<p>Message: %sveltekit.error.message%</p>
	</body>
</html>

SvelteKit replaces these placeholders:

%sveltekit.status% → HTTP status code
%sveltekit.error.message% → Error message

In load functions

If an error occurs inside a load function, SvelteKit renders the nearest +error.svelte component.

Error boundary rules

Errors in +page.server.js or +page.js render the nearest sibling +error.svelte
Errors in +layout.server.js or +layout.js render the nearest parent +error.svelte (not the sibling)
Errors in root +layout.js or +layout.server.js use the fallback error page

Type safety

Customize the shape of errors with TypeScript:

src/app.d.ts

declare global {
	namespace App {
		interface Error {
			code: string;
			id: string;
		}
	}
}

export {};

The App.Error interface always includes a message: string property.

Error helper reference

From @sveltejs/kit:

function

Throws an HTTP error with a status code and message

import { error } from '@sveltejs/kit';

error(404, 'Not found');
error(403, { message: 'Forbidden', code: 'ACCESS_DENIED' });

function

Checks if an error was thrown by the error helper

import { isHttpError } from '@sveltejs/kit';

try {
  // ...
} catch (e) {
  if (isHttpError(e, 404)) {
    // Handle 404 specifically
  }
}

Common patterns

import { error } from '@sveltejs/kit';

export async function load({ locals }) {
	if (!locals.user) {
		error(401, 'Not logged in');
	}
	
	if (!locals.user.isAdmin) {
		error(403, 'Not an admin');
	}
}

import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';

export async function load({ params }) {
	const item = await db.getItem(params.id);
	
	if (!item) {
		error(404, {
			message: 'Item not found',
			code: 'ITEM_NOT_FOUND'
		});
	}
	
	return { item };
}

import { error } from '@sveltejs/kit';

export async function load() {
	const errorId = crypto.randomUUID();
	
	// Log to monitoring service
	await logError(errorId, 'Invalid request');
	
	error(400, {
		message: 'Invalid request',
		errorId
	});
}

Learn more

Follow the interactive tutorial on errors and redirects

Getting Started

Core Concepts

Build and Deploy

Advanced

Error objects

Expected errors

Displaying errors

Adding custom properties

Shorthand syntax

Unexpected errors

handleError hook

Error responses

In handle or +server.js

Custom fallback page

In load functions

Type safety

Error helper reference

Common patterns

Learn more

​Error objects

​Expected errors

​Displaying errors

​Adding custom properties

​Shorthand syntax

​Unexpected errors

​handleError hook

​Error responses

​In handle or +server.js

​Custom fallback page

​In load functions

​Type safety

​Error helper reference

​Common patterns

Learn more

Error objects

Expected errors

Displaying errors

Adding custom properties

Shorthand syntax

Unexpected errors

handleError hook

Error responses

In handle or +server.js

Custom fallback page

In load functions

Type safety

Error helper reference

Common patterns