Manejo de Errores con +error.svelte

En un mundo perfecto, el código nunca falla. En el mundo real, las APIs se caen, las bases de datos se agotan, 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 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 UI alternativa en lugar de dejar que el error se propague hacia arriba y rompa 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 cercano y renderiza el error ahí, manteniendo intactos todos los layouts superiores. Un post de blog que falla no derriba el índice del blog. Un widget del dashboard que falla no elimina la navegación.

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

Los usuarios encontrarán errores. Lo que importa es si tienen un camino claro a seguir cuando eso ocurre. Un límite de error bien ubicado con acciones de recuperación útiles — un cuadro de búsqueda en 404, un botón de reintento en 500, un enlace de inicio de sesión en 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 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 a través de 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 ahí, 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án desorientados. Pueden 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 UI superior. Un +error.svelte en la raíz captura todo pero no tiene UI superior 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 de sección que coinciden 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 reiniciar 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 manejado (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

Incluir Acciones Útiles

<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 cuidadoso 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 significa comprender la distinción entre errores esperados (lanzados con error()) y errores inesperados (capturados por handleError). Los errores esperados deben proporcionar orientación clara al usuario y rutas de recuperación, mientras que los errores inesperados requieren registro, monitoreo y degradación elegante.

Al diseñar páginas de error que mantienen la apariencia de tu aplicación, proporcionan acciones útiles y respetan la jerarquía de layouts, construyes aplicaciones que fallan con elegancia y mantienen la confianza del usuario incluso cuando las cosas salen mal.

Puntos Clave

+error.svelte crea páginas de límite de error que capturan errores en funciones de carga y componentes de página, renderizando una UI de respaldo 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 mensajería amigable para el usuario
Las páginas de error se propagan desde el límite más cercano - SvelteKit busca hacia arriba en el árbol de rutas el +error.svelte más cercano, recurriendo a la raíz si no existe ninguno
Accede a los detalles del error mediante page de $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 padre manteniendo la navegación, encabezados y una UI consistente incluso durante los fallos
El hook handleError registra errores inesperados en hooks.server.ts, habilitando el monitoreo de errores, la sanitización y el registro antes de que los errores lleguen a los clientes
Diseña páginas de error con acciones de recuperación - cajas 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), 500 (error del servidor) con mensajería y acciones apropiadas

Ver También

Documentación Oficial de SvelteKit - Manejo de Errores
Helper error() - Lanzar errores esperados
Hook handleError - Registrar errores inesperados
page de $app/state — Acceder a detalles de 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