Manejo de Errores con +error.svelte

En un mundo perfecto, el código nunca falla. En el mundo real, las APIs caen, las bases de datos agotan el tiempo de espera, los usuarios escriben URLs incorrectas y las sesiones expiran a mitad de una solicitud. SvelteKit tiene un sistema robusto para manejar estas situaciones de forma elegante con los archivos +error.svelte.

¿Qué es un Límite de Error?

Un límite de error es un componente que captura los errores lanzados por sus descendientes y renderiza una interfaz de reserva en lugar de dejar que el error se propague y colapse toda la aplicación. Si una función de carga lanza un error, SvelteKit deja de renderizar esa ruta y busca el +error.svelte más cercano en la jerarquía de rutas para renderizarlo en su lugar.

La palabra clave es más cercano. SvelteKit no siempre recurre a una página de error global — busca el +error.svelte del ancestro más próximo y renderiza el error allí, manteniendo intactos todos los layouts superiores. Un post de blog fallido no derrumba el índice del blog. Un widget fallido del panel de control no elimina la navegación.

Esta contención del "radio de explosión" es lo que distingue una experiencia de error profesional de una deficiente. En lugar de una pantalla en blanco que pierde al usuario por completo, un error en una parte de tu aplicación produce una reserva elegante exactamente en esa parte — el resto de la interfaz sigue funcionando.

Los usuarios encontrarán errores. Lo que importa es si tienen un camino claro a seguir cuando eso sucede. Un límite de error bien ubicado con acciones de recuperación útiles — un cuadro de búsqueda en el 404, un botón de reintento en el 500, un enlace de inicio de sesión en el 401 — mantiene a los usuarios comprometidos. Una pantalla en blanco los pierde.

Creando una Página de Error

Tu archivo +error.svelte recibe los detalles del error a través del estado page:

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

<div class="error-container">
	<h1>{page.status}</h1>
	<p class="message">{page.error?.message}</p>

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

<style>
	.error-container {
		text-align: center;
		padding: 4rem 2rem;
	}

	h1 {
		font-size: 6rem;
		margin: 0;
		color: var(--brand);
	}

	.message {
		font-size: 1.25rem;
		color: var(--text-dimmed);
		margin-bottom: 2rem;
	}

	a {
		display: inline-block;
		padding: 0.75rem 1.5rem;
		background: var(--brand);
		color: white;
		text-decoration: none;
		border-radius: 4px;
	}
</style>

Lanzando Errores Esperados

A veces sabes que algo está mal. Por ejemplo, si un usuario solicita un post de blog que no existe, eso es un error 404. Puedes activarlo manualmente usando el helper error:

// src/routes/blog/[slug]/+page.ts
import { error } from '@sveltejs/kit'
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (response.status === 404) {
		// Stop execution and show the error page
		error(404, {
			message: 'Post not found',
			hint: 'The post you are looking for might have been removed.'
		})
	}

	if (!response.ok) {
		error(response.status, 'Failed to load post')
	}

	return {
		post: await response.json()
	}
}

Forma del Objeto de Error

La función error() acepta:

Un código de estado (400, 404, 500, etc.)
Una cadena de texto como mensaje O un objeto con propiedades personalizadas

// Simple message
error(404, 'Not found')

// Object with custom properties
error(403, {
	message: 'Access denied',
	hint: 'You need to be logged in to view this page.',
	code: 'AUTH_REQUIRED'
})

Accediendo a los Detalles del Error

En tu +error.svelte, accede al error mediante page.error:

<script lang="ts">
	import { page } from '$app/state'
</script>

<h1>Error {page.status}</h1>
<p>{page.error?.message}</p>

{#if page.error?.hint}
	<p class="hint">{page.error.hint}</p>
{/if}

{#if page.status === 404}
	<div class="suggestions">
		<h2>You might be looking for:</h2>
		<ul>
			<li><a href="/blog">Blog</a></li>
			<li><a href="/docs">Documentation</a></li>
			<li><a href="/">Homepage</a></li>
		</ul>
	</div>
{/if}

Páginas de Error en Cascada

Las páginas de error se propagan hacia arriba a través de la jerarquía de rutas. SvelteKit busca el archivo +error.svelte más cercano y renderiza el error allí, dentro de todos los layouts superiores:

src/routes/
├── +error.svelte              → Global fallback (inside root layout)
├── +layout.svelte
├── blog/
│   ├── +error.svelte          → Blog-specific errors (inside root layout)
│   ├── +layout.svelte
│   └── [slug]/
│       └── +page.ts           → If this throws...

Si src/routes/blog/[slug]/+page.ts lanza un error:

SvelteKit verifica src/routes/blog/[slug]/+error.svelte — no encontrado
Verifica src/routes/blog/+error.svelte — encontrado, renderiza este
El +layout.svelte raíz lo envuelve, por lo que el usuario sigue viendo la navegación de tu sitio

Esto significa que la página de error del blog se renderiza dentro del layout raíz. El usuario ve el mensaje de error, pero todavía tiene el encabezado, pie de página y navegación del sitio. No está abandonado. Puede ir a otro lugar.

Por eso importa la ubicación: un +error.svelte junto a una página profundamente anidada captura solo los errores de esa página y se renderiza dentro de toda la interfaz de los layouts superiores. Un +error.svelte en la raíz captura todo pero no tiene interfaz de layouts superiores que lo envuelva. Elige la ubicación según cuánto contexto quieras preservar cuando algo falle.

Esto permite páginas de error específicas por sección que coincidan con la identidad de la sección:

<!-- src/routes/blog/+error.svelte -->
<script lang="ts">
	import { page } from '$app/state'
</script>

<div class="blog-error">
	<h1>Oops! {page.status}</h1>
	<p>{page.error?.message}</p>

	<h2>Recent Posts</h2>
	<!-- Keep the user engaged with other content -->
	<a href="/blog">Browse all posts</a>
</div>

Contexto de Layout en Páginas de Error

Las páginas de error se renderizan dentro de su layout superior. Esto significa que tu encabezado y pie de página siguen apareciendo:

Root Layout (+layout.svelte)
├── Header
├── Main
│   └── Error Page (+error.svelte) ← Renders here
└── Footer

Si quieres que la página de error reemplace toda la página (sin layout), necesitas restablecer el layout:

src/routes/
├── +layout.svelte
├── +error.svelte      → Uses root layout
└── +error@.svelte     → Resets to NO layout (bare page)

Diferentes Tipos de Error

404 - No Encontrado

// Page doesn't exist
error(404, 'Page not found')

// Resource doesn't exist
error(404, {
	message: 'User not found',
	hint: 'This account may have been deleted.'
})

403 - Prohibido

error(403, {
	message: 'Access denied',
	hint: "You don't have permission to view this resource."
})

401 - No Autorizado

// Usually redirect instead, but sometimes error is appropriate
error(401, 'Please log in to continue')

500 - Error del Servidor

// Don't expose internal details to users
error(500, 'Something went wrong. Please try again later.')

Manejo de Errores Inesperados

Cuando ocurre un error no controlado (un bug en tu código), SvelteKit:

Registra el error completo en la consola del servidor
Muestra un error genérico al usuario (ocultando detalles sensibles)

Puedes personalizar esto en hooks.server.ts:

// src/hooks.server.ts
import type { HandleServerError } from '@sveltejs/kit'

export const handleError: HandleServerError = async ({ error, event, status, message }) => {
	// Log the full error for debugging
	console.error('Unexpected error:', error)

	// Send to error tracking service
	await reportToSentry(error, {
		url: event.url.pathname,
		userId: event.locals.user?.id
	})

	// Return a safe error message for the user
	return {
		message: 'An unexpected error occurred',
		code: 'INTERNAL_ERROR'
	}
}

Diseñando Buenas Páginas de Error

Incluye Acciones de Ayuda

<script lang="ts">
	import { page } from '$app/state'

	function goBack() {
		history.back()
	}
</script>

<div class="error-page">
	<h1>{page.status === 404 ? 'Page Not Found' : 'Something Went Wrong'}</h1>
	<p>{page.error?.message}</p>

	<div class="actions">
		<button onclick={goBack}>Go Back</button>
		<a href="/">Home</a>
		<a href="/contact">Report Issue</a>
	</div>
</div>

Contenido Específico por Estado

<script lang="ts">
	import { page } from '$app/state'

	const errorContent = {
		404: {
			title: 'Page Not Found',
			emoji: '🔍',
			suggestion: "The page you're looking for doesn't exist."
		},
		403: {
			title: 'Access Denied',
			emoji: '🔒',
			suggestion: "You don't have permission to view this page."
		},
		500: {
			title: 'Server Error',
			emoji: '💥',
			suggestion: 'Something went wrong on our end. Please try again.'
		}
	}

	let content = $derived(
		errorContent[page.status] ?? {
			title: 'Error',
			emoji: '⚠️',
			suggestion: page.error?.message
		}
	)
</script>

<div class="error-page">
	<span class="emoji">{content.emoji}</span>
	<h1>{content.title}</h1>
	<p>{content.suggestion}</p>
</div>

Lógica de Reintento

Para errores transitorios, ofrece una opción de reintento:

<script lang="ts">
	import { invalidateAll } from '$app/navigation'
	import { page } from '$app/state'

	let retrying = $state(false)

	async function retry() {
		retrying = true
		await invalidateAll()
		retrying = false
	}
</script>

{#if page.status >= 500}
	<button onclick={retry} disabled={retrying}>
		{retrying ? 'Retrying...' : 'Try Again'}
	</button>
{/if}

Conclusión

El manejo de errores en SvelteKit representa un equilibrio bien pensado entre redes de seguridad automáticas y control explícito. Al proporcionar archivos +error.svelte en puntos estratégicos de tu jerarquía de rutas, creas límites de error en cascada que capturan fallos y presentan alternativas amigables para el usuario en lugar de pantallas en blanco o errores genéricos del navegador.

El helper error() transforma los fallos de validación y los errores de lógica de negocio en respuestas de error estructuradas que fluyen naturalmente a través de la jerarquía de layouts de tu aplicación.

Dominar el manejo de errores implica entender la distinción entre errores esperados (lanzados con error()) y errores inesperados (capturados por handleError). Los errores esperados deben proporcionar una guía clara al usuario y rutas de recuperación, mientras que los errores inesperados requieren registro, monitoreo y degradación controlada.

Al diseñar páginas de error que mantengan el aspecto y la sensación de tu aplicación, ofrezcan acciones de ayuda y respeten la jerarquía de layouts, construyes aplicaciones que fallan de forma controlada y mantienen la confianza del usuario incluso cuando algo sale mal.

Puntos Clave

+error.svelte crea páginas de límite de error que capturan errores en funciones load y componentes de página, renderizando una UI alternativa en lugar de romper toda la aplicación
El helper error() señala errores estructurados con códigos de estado HTTP y mensajes: error(404, 'Post not found') devuelve una respuesta 404 con mensajes amigables para el usuario
Las páginas de error se aplican en cascada desde el límite más cercano - SvelteKit busca en el árbol de rutas el +error.svelte más cercano, y recurre al raíz si no existe ninguno
Accede a los detalles del error mediante page desde $app/state — page.status proporciona el código de estado HTTP y page.error contiene el mensaje de error y cualquier propiedad personalizada que hayas pasado a error()
Las páginas de error se renderizan dentro de los layouts padres manteniendo la navegación, encabezados y una UI consistente incluso durante los fallos
El hook handleError registra errores inesperados en hooks.server.ts, permitiendo el monitoreo, la sanitización y el registro de errores antes de que lleguen a los clientes
Diseña páginas de error con acciones de recuperación - cuadros de búsqueda para errores 404, botones de reintento para errores 500, enlaces de navegación para ayudar a los usuarios a continuar su recorrido
El contenido específico por estado mejora la UX - diferencia entre 404 (no encontrado), 403 (prohibido) y 500 (error del servidor) con mensajes y acciones apropiados

Ver También

Documentación Oficial de SvelteKit - Manejo de Errores
Helper error() - Lanzar errores esperados
Hook handleError - Registrar errores inesperados
page desde $app/state — Acceder a detalles del error, ruta y URL en componentes
Códigos de Estado HTTP - Significados de los códigos de estado estándar
Monitoreo de Errores - Seguimiento y alertas de errores en producción