Skip to main content

Erreurs

Les erreurs sont une réalité inévitable du développement logiciel. SvelteKit gère les erreurs de manière différente selon l’endroit où elles se produisent, leur type, et la nature de la requête entrante.

Objets d’erreurs

SvelteKit distingue les erreurs prévues et imprévues, les deux typologies étant représentées en tant que simple objets { message: string } par défaut.

Vous pouvez ajouter des propriétés additionnelles, comme code ou un id de suivi, comme montré dans les exemples ci-dessous. (Lorsque vous utilisez TypeScript ceci requiert que vous redéfinissiez le type Error comme décrit dans la section sur typage).

Erreurs prévues

Une erreur prévue est une erreur créée avec l’utilitaire error importé depuis @sveltejs/kit :

src/routes/blog/[slug]/+page.server
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	const post = await db.getPost(params.slug);

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

	return { post };
}
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';
import type { PageServerLoad } from './$types';

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

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

	return { post };
};

Ceci lève une exception que SvelteKit attrape, lui permettant de définir le statut de la réponse à 404 et de rendre le composant +error.svelte approprié, dans lequel page.error est l’objet fourni en tant que second argument à error(...).

src/routes/+error
<script>
	import { page } from '$app/state';
</script>

<h1>{page.error.message}</h1>
<script lang="ts">
	import { page } from '$app/state';
</script>

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

$app/state a été ajouté dans la version 2.12 de SvelteKit. Si vous utilisez une version plus récente ou si vous utilisez Svelte 4, veuillez plutôt utiliser $app/stores.

Vous pouvez ajouter des propriétés additionnelles à l’objet d’erreur si besoin...

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

... ou bien fournir une chaîne de caractères en tant que deuxième argument, pour plus de simplicité :

error(404, { message: 'Introuvable' });
error(404, 'Introuvable');

Dans SvelteKit 1.x vous deviez lever une error vous-même avec throw.

Erreurs imprévues

Une erreur imprévue est toute autre exception se produisant pendant le traitement d’une requête. Puisque celles-ci peuvent contenir des informations sensibles, les messages d’erreur et stacktraces ne sont pas exposées aux utilisateurs et utilisatrices.

Par défaut, les erreurs imprévues sont affichées dans la console, (ou, en production, dans vos logs de serveur), tandis que l’erreur exposée aux utilisateurs et utilisatrices reste générique :

{ "message": "Internal Error" }

Les erreurs inattendues vont être passées au hook handleError, où vous pouvez ajouter votre propre gestion d’erreur — par exemple, envoyer ces erreurs à un service de suivi d’erreur, ou renvoyer un objet d’erreur personnalisé qui va devenir page.error.

Afficher les erreurs

Normalement, si une erreur se produit lors du rendu côté serveur (par exemple dans le bloc <script> ou dans le markup), SvelteKit renverra une page d’erreur 500.

Depuis les versions 2.54 de SvelteKit et 5.53 de Svelte, vous pouvez changez ceci en activant l’option expérimentale handleRenderingErrors dans votre fichier de configuration :

svelte.config
/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		experimental: {
			handleRenderingErrors: true
		}
	}
};

export default config;

Lorsque cette option est activée, SvelteKit va entourer vos composants de route d’une frontière d’erreur. Si une erreur se produit alors lors du rendu, la page +error.svelte la plus proche sera affichée, de la même manière que si l’erreur s’était produite dans une fonction load.

L’erreur est d’abord passée à handleError, vous permettant de la signaler et de la transformer, avant que l’objet ainsi construit ne soit fourni au composant +error.svelte.

Puisque le rendu des erreurs se produit après que la page ait commencé son rendu, et que plusieurs frontières peuvent en parallèle attraper plusieurs erreurs distinctes, l’objet page (et sa propriété error) ne sera pas mis à jour. À la place, l’erreur est passée directement au composant +error.svelte en tant que prop.

+error
<script>
	let { error } = $props();
</script>

<h1>{error.message}</h1>
<script lang="ts">
	let { error } = $props();
</script>

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

Ceci vaut également pour les autres frontières d’erreur que vous définissez dans votre code :

<svelte:boundary>
	...
	{#snippet failed(error: App.Error)}
		<!-- l'erreur est passée par handelError et est de type App.Error -->
		{error.message}
	{/snippet}
</svelte:boundary>

Réponses

Si une erreur se produit au sein de la fonction handle ou d’un gestionnaire de requête +server.js, SvelteKit va répondre avec soit une page d’erreur de secours, soit une représentation JSON de l’objet d’erreur, en fonction des en-têtes de requête Accept.

Vous pouvez personnaliser la page d’erreur de secours en ajoutant un fichier src/error.html :

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>%sveltekit.error.message%</title>
	</head>
	<body>
		<h1>Ma page d'erreur personnalisée</h1>
		<p>Statut : %sveltekit.status%</p>
		<p>Message : %sveltekit.error.message%</p>
	</body>
</html>

SvelteKit va remplacer %sveltekit.status% et %sveltekit.error.message% avec leurs valeurs respectives.

Si l’erreur se produit plutôt au sein d’une fonction load lors du rendu d’une page, SvelteKit va rendre le composant +error.svelte le plus proche de là où l’erreur s’est produite. Si l’erreur se produit au sein d’une fonction load d’un fichier +layout(.server).js, la frontière d’erreur la plus proche est un fichier +error.svelte au-dessus de ce layout (et non à côté).

Il y a une exception lorsque l’erreur se produit au sein du fichier +layout.js ou +layout.server.js racine, puisque le layout racine devrait normalement contenir le composant +error.svelte. Dans ce cas, SvelteKit va utiliser la page d’erreur de secours.

Typage

Si vous utilisez TypeScript et avez besoin de personnaliser la forme des erreurs, vous pouvez le faire en déclarant une interface App.Error dans votre application (par convention, dans le fichier src/app.d.ts, bien qu’il puisse se trouver dans n’importe dossier dont TypeScript a connaissance) :

src/app.d
declare global {
	namespace App {
		interface Error {
			code: string;
			id: string;
		}
	}
}

export {};

Cette interface va toujours inclure une propriété message: string.

Plus de lecture

Modifier cette page sur Github llms.txt

précédent suivant