Cómo las Funciones Load Se Detienen Anticipadamente

Las funciones load fallan por todo tipo de razones ordinarias: un usuario busca un registro que no existe, su sesión ha expirado, no tiene permiso para ver la página, o una API externa está temporalmente caída. En cada caso, continuar ejecutando la función load y retornar datos incompletos causaría más problemas de los que resuelve. Puede resultar en un componente roto, un error de runtime críptico, o peor, servir silenciosamente contenido protegido.

SvelteKit te provee dos funciones para manejar estas situaciones de manera limpia: error() para renderizar una página de error, y redirect() para enviar al usuario a otro lugar. Ambas se importan desde @sveltejs/kit y ambas funcionan de la misma manera; las llamas y detienen inmediatamente la función load lanzando una excepción internamente. No necesitas escribir throw tú mismo.

También existe una tercera categoría que vale la pena conocer: errores que no anticipaste en absoluto, como un timeout de red, una falla al parsear JSON, una desreferencia de null. SvelteKit también captura estos y los enruta a través de un hook separado llamado handleError. El usuario ve una página de error genérica; los detalles internos van a tu sistema de logging.

Lo más importante que debes entender antes de usar cualquiera de estas herramientas es que redirect() y error() funcionan lanzando excepciones. Cualquier bloque try/catch que los envuelva atrapará accidentalmente la señal antes de que SvelteKit la vea. Ese único error (envolver una redirección en un try/catch) es cómo los guardias de rutas dejan de funcionar silenciosamente en producción. Este artículo cubre los tres caminos, en el orden en que probablemente los necesitarás.

Cuando una Función Load No Puede Retornar Datos

Imagina una página de dashboard. La función load obtiene los datos del usuario autenticado. Tres cosas pueden ocurrir cuando llega una solicitud. El usuario está autenticado y los datos cargan correctamente. El usuario no está autenticado en absoluto, y la respuesta correcta es redirigirlo a una página de inicio de sesión. El usuario está autenticado pero la API de datos retorna un 500, y la respuesta correcta es una página de error que explica que algo falló.

Cada uno de estos resultados necesita una instrucción diferente para SvelteKit. Retornar los datos es el camino exitoso. Pero para los caminos de falla, simplemente retornar un objeto vacío o null no funciona. El componente de página recibiría datos incompletos, intentaría renderizarlos y produciría una página rota o un error de runtime que SvelteKit capturaría como un error inesperado en lugar de uno controlado.

En SvelteKit tenemos dos herramientas para fallas controladas: error() y redirect(), ambas importadas desde @sveltejs/kit. No son funciones de utilidad que retornan valores que luego lanzas tú mismo. Son funciones que lanzan internamente. Las llamas directamente, sin throw. Cuando su ejecución llega a los internos de SvelteKit, el lanzamiento termina la función load y transfiere el control al manejador de framework apropiado.

También existe una tercera categoría: errores que no tenías intención de lanzar en absoluto — un timeout de red, falla al parsear JSON, una desreferencia de null, etc. Estos son errores inesperados, y SvelteKit los enruta a través de un mecanismo diferente llamado handleError en hooks.server.ts. Los errores inesperados también renderizan una página de error, pero la información expuesta al usuario es deliberadamente mínima, y los detalles van a tu sistema de logging en su lugar.

Los Cuatro Resultados Posibles

Toda ejecución de una función load termina de una de cuatro maneras. Verlos juntos antes de entrar en los detalles hace que el resto del artículo sea más fácil de navegar.

Los cuatro caminos son mutuamente excluyentes. Tu responsabilidad es elegir el camino correcto para cada condición y no interceptar accidentalmente una redirección o error lanzado tú mismo, lo cual es la falla silenciosa de la que más se preocupa este artículo.

Errores Esperados con error()

Un error esperado es una condición que tu función load anticipa y señala explícitamente. Un 404 porque un slug no corresponde a ningún registro. Un 403 porque el usuario no tiene el permiso requerido. Un 503 porque una dependencia está caída y quieres comunicarlo claramente. Estos son errores que eliges lanzar.

La función error() toma dos argumentos:

un código de estado HTTP
un mensaje.

import { error } from '@sveltejs/kit'
// error(status: number, message: string | { message: string; [key: string]: any })

error(404, 'Not found')

Los códigos de estado más utilizados en funciones load:

Código	Nombre	Cuándo usarlo
`400`	Bad Request	Los parámetros de query o de ruta están malformados o son inválidos.
`401`	Unauthorized	El usuario no está autenticado (sin sesión, token expirado).
`403`	Forbidden	El usuario sí está autenticado pero carece de permiso para este recurso.
`404`	Not Found	El registro o página solicitada no existe.
`410`	Gone	El recurso existía pero fue eliminado permanentemente. Preferir sobre 404 cuando la eliminación es intencional y permanente.
`429`	Too Many Requests	El usuario o cliente ha superado un límite de tasa.
`500`	Internal Server Error	Una dependencia falló de manera inesperada.
`503`	Service Unavailable	Un servicio upstream requerido está temporalmente caído.

El mensaje puede ser un string o un objeto con una propiedad message. SvelteKit lanza un HttpError internamente y termina la función load.

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

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

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

	if (response.status === 404) {
		// Signal to SvelteKit that this is an expected, understood condition.
		// The string 'Post not found' will be available in +error.svelte
		// via page.error.message.
		error(404, 'Post not found')
	}

	if (!response.ok) {
		// A non-404 failure is still an expected category here.
		// The status code is passed through so the error page can
		// display or log it appropriately.
		error(response.status, 'Failed to load post')
	}

	const post = await response.json()
	return { post }
}

Después de que se llama a error(), nada debajo de él en la función load se ejecuta. No hay valor de retorno. SvelteKit intercepta el HttpError lanzado y comienza a enrutarlo hacia el archivo +error.svelte más cercano en la jerarquía de rutas.

El mensaje que pasas a error() está intencionalmente orientado al usuario. Mantenlo claro y honesto pero no verboso. Es lo que tu página de error mostrará. No es una entrada de log. No pongas stack traces, nombres de servicios internos, o mensajes de error de base de datos en el mensaje de error(). Esos pertenecen a los logs del servidor, no al navegador.

La forma de objeto del mensaje es útil cuando quieres adjuntar información estructurada adicional al error y leerla en el componente de error:

// src/routes/admin/reports/[reportId]/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, locals, fetch }) => {
	if (!locals.user) {
		// A 401 with a structured message object.
		// The error component can read message.code to decide how to render.
		error(401, { message: 'Authentication required', code: 'UNAUTHENTICATED' })
	}

	const response = await fetch(`/api/reports/${params.reportId}`)

	if (response.status === 403) {
		error(403, { message: 'You do not have permission to view this report', code: 'FORBIDDEN' })
	}

	if (response.status === 404) {
		error(404, { message: `Report ${params.reportId} does not exist`, code: 'NOT_FOUND' })
	}

	if (!response.ok) {
		error(500, { message: 'Failed to load report data', code: 'SERVER_ERROR' })
	}

	const report = await response.json()
	return { report }
}

El campo code en el objeto de mensaje no es una convención de SvelteKit. Es un campo personalizado que define tu aplicación. SvelteKit pasa el objeto de mensaje completo a través de page.error, por lo que cualquier forma que le des estará disponible en el componente de error. Úsalo de manera consistente en toda tu aplicación para que las páginas de error puedan renderizar mensajes contextualmente apropiados.

Cómo SvelteKit Enruta hacia +error.svelte

Cuando se lanza error() desde una función load, SvelteKit sube por la jerarquía de rutas buscando el archivo +error.svelte más cercano. La búsqueda comienza en el mismo nivel que la función load que lanzó el error y se mueve hacia la raíz.

Route that throws: src/routes/blog/[slug]/+page.server.ts

SvelteKit looks for +error.svelte in this order:

  1. src/routes/blog/[slug]/+error.svelte     (most specific, checked first)
  2. src/routes/blog/+error.svelte            (blog section level)
  3. src/routes/+error.svelte                 (root level, catches everything)

El primer archivo +error.svelte encontrado en este recorrido es el que se renderiza. Si no existe ninguno en la jerarquía, SvelteKit recurre a su página de error incorporada.

Esta jerarquía es intencional. Un 404 en una publicación de blog no necesita verse igual que un 404 en la página de pago. Al colocar archivos +error.svelte en diferentes niveles, puedes darle a las secciones de tu aplicación su propia presentación de errores mientras aún tienes un fallback en la raíz.

El componente +error.svelte recibe información del error a través del store page del módulo $app/state. El campo page.status contiene el código de estado HTTP. El campo page.error contiene el valor del mensaje pasado a error().

<!-- src/routes/+error.svelte -->
<!-- Root-level error page. Handles all unmatched errors. -->

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

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

	<p class="error-message">
		{page.error?.message ?? 'An unexpected error occurred.'}
	</p>

	{#if page.status === 404}
		<p>The page you are looking for does not exist or has been moved.</p>
	{:else if page.status === 403}
		<p>You do not have permission to access this resource.</p>
	{:else if page.status >= 500}
		<p>Something went wrong on our end. Please try again in a moment.</p>
	{/if}

	<nav class="error-nav">
		<a href="/">Return to home</a>
	</nav>
</div>

<!-- src/routes/blog/+error.svelte -->
<!-- Blog-section error page. Only handles errors thrown from blog routes. -->
<!-- Falls through to +error.svelte at root level if not present here. -->

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

<div class="blog-error">
	<h1>
		{#if page.status === 404}
			Article Not Found
		{:else}
			Something Went Wrong
		{/if}
	</h1>

	<p>{page.error?.message}</p>

	<div class="blog-error-actions">
		<a href="/blog">Browse all articles</a>
		<a href="/">Return to home</a>
	</div>
</div>

Un detalle importante sobre el layout: el archivo +error.svelte se renderiza dentro del layout más cercano que también tiene su propio +error.svelte definido en ese nivel o superior. No se renderiza de manera aislada. Esto significa que la navegación, las fuentes y los estilos globales de tu layout raíz siguen presentes cuando se renderiza la página de error, dándote una experiencia de usuario coherente sin duplicar la estructura del layout en cada componente de error.

Redirecciones con redirect()

La función redirect() de @sveltejs/kit termina una función load e instruye a SvelteKit para enviar una respuesta de redirección al navegador. Al igual que error(), funciona lanzando internamente.

La función redirect() toma dos argumentos:

un código de estado HTTP — debe estar en el rango 300–308
una URL de destino — un string de ruta o URL completa

import { redirect } from '@sveltejs/kit'
// redirect(status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308, location: string | URL)

redirect(303, '/login')
redirect(301, 'https://example.com/new-url')

Nada después de redirect() se ejecuta. La función load termina en el momento en que se lanza la redirección.

El primer argumento es el código de estado HTTP. Para redirecciones en funciones load, el rango válido es 300 a 308. La elección del código de estado tiene un significado semántico del que dependen los navegadores, los motores de búsqueda y los cachés HTTP. Elegir el incorrecto puede causar redirecciones cacheadas obsoletas, comportamiento roto del botón de retroceso, o cambios de método en envíos de formularios.

Los códigos más útiles en funciones load de SvelteKit son 303 y 307.

El estado 303 significa "see other" (ver otro) e instruye al cliente a hacer una solicitud GET a la nueva ubicación, independientemente del método usado en la solicitud original.

El estado 307 significa "temporary redirect" (redirección temporal) y preserva el método HTTP, lo que significa que un POST a una URL redirigida hará POST a la nueva ubicación en lugar de GET.

Para el caso común de redirigir a un usuario después de la autenticación (enviar a un visitante no autenticado a la página de inicio de sesión), 303 es casi siempre correcto. El usuario llegó mediante GET. Debería ser redirigido a otro GET. El estado 308 es el equivalente permanente de 307, apropiado para contenido que se ha movido a una URL canónica para siempre y debe actualizarse en los índices de motores de búsqueda.

Código	Nombre	Método	Duración	Cuándo usarlo
`301`	Moved Permanently	Solo GET	Permanente	La URL ha cambiado para siempre. Los navegadores y motores de búsqueda la cachean — la URL original nunca debería usarse de nuevo.
`302`	Found	Solo GET (en la práctica)	Temporal	Ampliamente usado pero ambiguo. Algunos clientes antiguos preservan el método original; la mayoría no. Evitar en favor de 303 o 307.
`303`	See Other	Siempre GET	Temporal	Elección predeterminada para redirecciones de autenticación. Envía usuarios no autenticados al inicio de sesión. Siempre resulta en un GET independientemente del método original.
`307`	Temporary Redirect	Preserva el método	Temporal	Usar cuando se redirige un POST a otra URL que también debería recibir un POST.
`308`	Permanent Redirect	Preserva el método	Permanente	Migraciones de URL canónica para endpoints que aceptan métodos distintos a GET.

Para el día a día práctico de los guardias de rutas en funciones load, elige 303. Es inequívoco, seguro para navegadores, y tiene la semántica correcta para redirecciones de autenticación.

La Trampa del try/catch

Ahora entramos a la sección más importante del artículo. Discutimos un error que parece razonable, porque su resultado no produce un error de runtime ni una advertencia, y silenciosamente deshabilita tu guardia de ruta por completo en producción.

Como sabemos, error() y redirect() funcionan lanzando excepciones, cualquier bloque try/catch que los envuelva capturará el valor lanzado e impedirá que SvelteKit lo vea. Por lo tanto, redirect() o error() nunca llegan al framework. La función load continúa ejecutándose (o termina) como si nada hubiera pasado.

Así es como se ve esto en el contexto de un guardia de ruta:

// Wrong: the try/catch swallows the redirect thrown by redirect().
// If the user is unauthenticated, redirect() is called, throws internally,
// and the catch block catches it. The load function returns undefined.
// SvelteKit receives no redirect instruction. The page loads anyway.

export const load: PageServerLoad = async ({ locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/user/dashboard`)
		const data = await response.json()
		return { dashboard: data }
	} catch (e) {
		// This catches the redirect thrown by redirect().
		// The developer intends this to catch fetch errors.
		// The result is that unauthenticated users see the dashboard.
		console.error('Load failed:', e)
		error(500, 'Failed to load dashboard')
	}
}

La solución es que necesitamos reestructurar el código para que redirect() y error() se llamen fuera de cualquier try/catch, o volver a lanzarlos si un try/catch es genuinamente necesario para otro manejo de errores:

// Correct: redirect() is called before the try/catch block.
// If the user is unauthenticated, redirect() throws and terminates
// the load function. The try/catch below never runs.

export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	try {
		const response = await fetch(`/api/user/dashboard`)

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

		const data = await response.json()
		return { dashboard: data }
	} catch (e) {
		// This try/catch now only wraps the fetch and JSON parse.
		// redirect() and error() above it are not caught here.
		// The catch block handles genuine unexpected failures like network errors.
		console.error('Unexpected load error:', e)
		error(500, 'An unexpected error occurred')
	}
}

Type guard isRedirect

Si por alguna razón debes llamar a redirect() dentro de un try/catch, necesitas volver a lanzar el valor de redirección después de detectarlo con el type guard isRedirect de @sveltejs/kit. Este es un patrón más propenso a errores, pero es importante conocerlo porque puedes encontrarlo en código existente:

import { redirect, error, isRedirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/user/dashboard`)
		return { dashboard: await response.json() }
	} catch (e) {
		// Re-throw redirect and error instances so SvelteKit can handle them.
		// Only catch genuine unexpected errors here.
		if (isRedirect(e)) throw e

		console.error('Unexpected error:', e)
		error(500, 'Something went wrong')
	}
}

Type guard isHttpError

El type guard isHttpError cumple el mismo propósito para las instancias de error(). Si estás capturando todos los errores en una función load y quieres dejar pasar las llamadas esperadas a error(), vuélvelas a lanzar junto con las redirecciones:

import { redirect, error, isRedirect, isHttpError } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, locals, fetch }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}

		const response = await fetch(`/api/posts/${params.slug}`)

		if (response.status === 404) {
			error(404, 'Post not found')
		}

		return { post: await response.json() }
	} catch (e) {
		if (isRedirect(e) || isHttpError(e)) throw e

		console.error('Unexpected error:', e)
		error(500, 'Failed to load post')
	}
}

Buenas Prácticas

La solución más limpia en la mayoría de los casos es reestructurar el código para que las verificaciones de guardia y los lanzamientos de error deliberados ocurran antes del try/catch. El try/catch solo debería envolver las líneas específicas de código que pueden lanzar errores inesperados, como fetch y response.json(). De esta manera evitas el riesgo de tragar accidentalmente una redirección o error esperado, y tu intención es más clara para futuros lectores.

El patrón de volver a lanzar existe para situaciones donde reestructurar no es práctico, pero requiere disciplina: cada bloque catch que pueda interceptar una redirección o error debe volver a lanzarlos explícitamente. Si olvidas volver a lanzar aunque sea uno, corres el riesgo de romper silenciosamente tus guardias de rutas y el manejo de errores de una manera que solo se manifiesta en producción.

La regla a memorizar: nunca pongas redirect() o error() dentro de un try/catch a menos que vuelvas a lanzar las instancias de redirect y error explícitamente.

Errores Inesperados

Un error inesperado es cualquier error que tu función load no señaló explícitamente con error(). Un await fallido en un fetch que lanza un error de red. Estos pueden ser: falla al parsear JSON, desreferencia de null porque una respuesta de API tenía una forma diferente a la esperada, new Error(...) lanzado desde una función de utilidad, etc. Estos son errores que no tenías intención de lanzar, pero que aún pueden ocurrir en el mundo real. No son esperados, pero tampoco son imposibles. Son la categoría "ups" de los errores.

Cuando ocurre un error inesperado, SvelteKit lo maneja invocando el hook handleError en src/hooks.server.ts, pasando el objeto de error, el evento de la solicitud, un código de estado y un mensaje. El hook es responsable de generar cualquier ID de error que necesite (por ejemplo, mediante crypto.randomUUID()). Después de esto, SvelteKit renderiza el +error.svelte más cercano con un código de estado de 500 y un mensaje genérico y no específico.

Este mensaje genérico es intencional. Los errores inesperados pueden incluir información interna sensible como rutas de archivos, consultas de base de datos, nombres de servicios, o incluso claves de API. Exponer estos detalles en el navegador representa riesgos de seguridad y privacidad. Por defecto, SvelteKit usa { message: 'Internal Error' } para errores inesperados, asegurando que no se revele información sensible.

El hook handleError es donde envías la información real del error a algún lugar útil, típicamente un servicio de logging o seguimiento de errores:

// src/hooks.server.ts

import type { HandleServerError } from '@sveltejs/kit'

// Note: the export name is 'handleError', not 'handleServerError'.
// 'HandleServerError' is the type; 'handleError' is what SvelteKit looks for.
export const handleError: HandleServerError = async ({ error, event, status, message }) => {
	// 'error' is the raw thrown value. May be an Error instance or anything else.
	// 'event' is the RequestEvent, giving you the URL, headers, and locals.
	// 'status' is the HTTP status code SvelteKit has assigned (usually 500).
	// 'message' is what SvelteKit will show the user ('Internal Error' by default).

	const errorId = crypto.randomUUID()

	// In production, send this to your error tracking service.
	// In development, logging to the console is sufficient.
	console.error({
		errorId,
		status,
		message: error instanceof Error ? error.message : String(error),
		stack: error instanceof Error ? error.stack : undefined,
		url: event.url.pathname,
		method: event.request.method
	})

	// The return value from handleError becomes page.error in +error.svelte.
	// Return something safe that is useful enough for debugging without
	// exposing internal implementation details.
	return {
		message: 'An unexpected error occurred.',
		errorId
	}
}

El valor de retorno de handleError reemplaza el { message: 'Internal Error' } predeterminado como el valor de page.error. Al retornar un errorId, la página de error puede mostrar a los usuarios un número de referencia que pueden proporcionar al contactar soporte, lo que te permite buscar los detalles completos en tu sistema de logging sin exponer jamás esos detalles directamente en el navegador.

La distinción entre errores esperados e inesperados importa para la experiencia del usuario.

Los errores esperados deben ser claros y accionables. Un 404 debe decirle al usuario que el contenido no fue encontrado y ofrecer un camino a seguir.
Los errores inesperados deben ser honestos sobre la falla mientras permanecen vagos sobre los internos. El hook handleError hace posible esta separación.

Ejemplo Práctico: Un Guardia de Ruta para Administradores

Una sección de administración es el escenario más claro para ver redirect(), error() y la jerarquía de enrutamiento de errores funcionando juntos en el mismo código. Cada concepto de este artículo aparece en una forma concreta y comprobable.

El ejemplo modela tres rutas de solicitud distintas, cada una produciendo un resultado diferente:

Ruta de solicitud	Quién	Qué ocurre
Sin cookie `sid`	Visitante anónimo	`redirect(303, '/login?returnTo=...')` — enviado al inicio de sesión, URL de retorno preservada
Cookie `sid` con `role: user`	Autenticado, rol incorrecto	`error(403, ...)` — `+error.svelte` de admin se renderiza con el mensaje 403
Cookie `sid` con `role: admin`	Autenticado, rol correcto	La carga es exitosa, la página se renderiza

El ejemplo es completamente autónomo. El almacén de sesiones y los datos de usuario están codificados de forma fija — no se requiere base de datos ni servicio externo.

Dos cuentas de prueba están disponibles una vez que conectes la página de inicio de sesión:

Valor de cookie (`sid`)	Usuario	Rol
`session-admin-123`	Alice Admin	`admin` — puede acceder a `/admin`
`session-user-456`	Bob User	`user` — choca con el guardia 403

La estructura completa de archivos:

src/
  app.d.ts                          ← augment App.Locals
  hooks.server.ts                   ← populate locals from cookie
  routes/
    +layout.server.ts               ← validate session, expose user to all pages
    +layout.svelte                  ← global layout
    +page.svelte                    ← home page
    login/
      +page.server.ts               ← fake login that sets the sid cookie
      +page.svelte                  ← set / clear the sid cookie
    admin/
      +layout.server.ts             ← auth + authz guard
      +layout.svelte                ← admin shell nav
      +error.svelte                 ← section-specific error page
      +page.svelte                  ← admin dashboard index
      users/
        +page.server.ts             ← fetch paginated users
        +page.svelte                ← render user list
    api/
      session/
        validate/
          +server.ts                ← fake session store
      admin/
        users/
          +server.ts                ← fake user data

Paso 1 — Tipar la sesión en App.Locals

Antes de escribir cualquier función load, dile a TypeScript qué forma tiene locals.user. Sin esto, cada acceso a locals.user en una función load de servidor o un hook es un any implícito.

// src/app.d.ts
declare global {
	namespace App {
		interface Locals {
			user: { id: string; name: string; role: string } | null
		}
	}
}
export {}

Esta única declaración hace que locals.user esté completamente tipado en todas partes — hooks, loads de layout, loads de página. Ajusta los campos para que coincidan con lo que retorna tu API de sesión real.

Paso 2 — Poblar locals una vez por solicitud en hooks.server.ts

El hook handle en hooks.server.ts se ejecuta antes de que se resuelva cada solicitud. Es el lugar adecuado para validar la cookie de sesión y adjuntar el usuario a event.locals — no dentro de una carga de layout.

La razón está directamente relacionada con la trampa del try/catch. Si la validación de sesión viviera dentro de una carga de layout envuelta en try/catch para el manejo de errores de fetch, una llamada descuidada a redirect() o error() podría ser absorbida. Ejecutarla en handle, antes de que se ejecute cualquier función de carga, significa que el usuario validado está disponible en locals en el momento en que cualquier función de carga lo lea. La función de carga puede entonces llamar a redirect() o error() de forma limpia, sin ningún try/catch cerca de ellas.

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	// Skip validation for the session endpoint itself to prevent
	// infinite recursion — event.fetch re-enters this hook.
	if (event.url.pathname === '/api/session/validate') {
		return resolve(event)
	}

	const sessionId = event.cookies.get('sid')

	if (sessionId) {
		const response = await event.fetch('/api/session/validate', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({ sessionId })
		})

		if (response.ok) {
			const { user } = await response.json()
			event.locals.user = user
		}
	}

	return resolve(event)
}

Si la cookie falta o es inválida, event.locals.user nunca se establece. Dado que App.Locals la declara como { ... } | null, TypeScript forzará que cada función de carga maneje el caso null.

Paso 3 — Exponer el usuario a las páginas públicas en el layout raíz

La carga del layout raíz se ejecuta para cada ruta en la aplicación. Obtiene la sesión por segunda vez — esta vez para poblar data.user para los componentes en el +layout.svelte raíz. Nótese que no llama a redirect() ni a error() aquí, porque la mayoría de las rutas son públicas. Los visitantes no autenticados deben poder acceder a la página de inicio sin ser redirigidos.

// src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('sid')

	if (!sessionId) {
		return { user: null }
	}

	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	if (!response.ok) {
		return { user: null }
	}

	const { user } = await response.json()
	return { user }
}

Retornar { user: null } es el patrón correcto para una ruta pública que no requiere autenticación. Las llamadas a redirect y error pertenecen a las cargas que realmente necesitan restringir el acceso.

Paso 4 — El guard del layout de admin: donde aparecen redirect() y error()

Este es el archivo central del ejemplo. El +layout.server.ts de admin es donde los dos caminos de fallo de este artículo se encuentran en una sola función de carga — redirect() para usuarios no autenticados, error() para usuarios autenticados sin el rol requerido.

// src/routes/admin/+layout.server.ts

import type { LayoutServerLoad } from './$types'
import { redirect, error } from '@sveltejs/kit'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	// Authentication check — no session means no business being here.
	// redirect(303) sends the user to login and preserves the current URL
	// as a returnTo param so they land back here after signing in.
	if (!locals.user) {
		redirect(303, `/login?returnTo=${encodeURIComponent(url.pathname)}`)
	}

	// Authorization check — the user IS authenticated, but lacks the role.
	// This is NOT a redirect to login. Their session is valid.
	// Sending them to login would imply the session is broken, which is wrong.
	// error(403) is the accurate signal: authenticated, not permitted.
	if (locals.user.role !== 'admin') {
		error(403, 'You do not have permission to access the admin section.')
	}

	// Both checks passed. Return the user for child layouts and pages to use.
	return { adminUser: locals.user }
}

Nótese lo que no está aquí: ningún try/catch. Las llamadas a redirect() y error() están en el nivel superior de la función de carga, sin estar envueltas en nada que pueda interceptar los throws. Este es exactamente el patrón descrito en la sección de la trampa del try/catch — primero las verificaciones de guard, luego las operaciones riesgosas (si las hay), en un try/catch separado que no rodea a los guards.

Dado que esta es una carga de layout, SvelteKit la ejecuta antes de ejecutar cualquier carga de página bajo /admin. Si el guard falla, la carga de página nunca se ejecuta. En el momento en que los archivos +page.server.ts bajo /admin se ejecutan, se garantiza que locals.user existe y tiene el rol de admin.

Paso 5 — Una carga de página de admin que depende del guard

Las cargas de página bajo /admin pueden omitir la re-verificación de autenticación y autorización. El guard del layout ya se ejecutó. Solo necesitan manejar los fallos específicos de obtención de datos que sus propias llamadas fetch pueden producir.

// src/routes/admin/users/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ url, fetch }) => {
	const page = Number(url.searchParams.get('page') ?? '1')
	const perPage = 25

	const response = await fetch(`/api/admin/users?page=${page}&perPage=${perPage}`)

	// error() here is a controlled failure for a fetch problem.
	// It is not inside a try/catch — it sits at the top level of the load.
	if (!response.ok) {
		error(response.status, 'Failed to load user list')
	}

	const { users, total } = await response.json()

	return {
		users,
		pagination: {
			page,
			perPage,
			total,
			totalPages: Math.ceil(total / perPage)
		}
	}
}

Paso 6 — El +error.svelte específico de admin

Colocar un +error.svelte dentro del directorio admin/ le da a la sección de admin su propia página de error. Cuando se lanza error(403, ...) desde el guard del layout de admin, SvelteKit recorre la jerarquía de rutas y encuentra este archivo antes de llegar al +error.svelte del nivel raíz.

<!-- src/routes/admin/+error.svelte -->

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

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

	{#if page.status === 403}
		<p>If you believe you should have access to this section, contact a superadmin.</p>
	{/if}

	<a href="/admin" class="admin-error-back">Return to admin dashboard</a>
</div>

page.status y page.error.message contienen exactamente lo que se pasó a error() en el guard del layout: 403 y 'You do not have permission to access the admin section.'. El componente de error los lee directamente — sin props, sin fetch adicional.

Este archivo también se renderiza dentro del layout de admin, por lo que la estructura de navegación permanece visible cuando ocurre un 403. Un usuario autenticado que llega a la página prohibida sigue viendo el marco de la aplicación, no una página en blanco. Si deseas que el error se renderice fuera del layout de admin — por ejemplo, para evitar que una nav de admin parcialmente renderizada confunda al usuario — elimina este archivo y deja que el error caiga hasta src/routes/+error.svelte.

Los archivos de soporte

Los archivos restantes son scaffolding que te permite ejercitar el guard en un navegador sin una base de datos real.

El componente de layout de admin renderiza la estructura de nav y el contenido de la página hija:

<!-- src/routes/admin/+layout.svelte -->

<script lang="ts">
	import type { LayoutProps } from './$types'

	let { data, children }: LayoutProps = $props()
</script>

<div class="admin-shell">
	<nav class="admin-nav">
		<span class="admin-badge">Admin</span>
		<span class="admin-user">{data.adminUser.name}</span>
		<ul class="admin-links">
			<li><a href="/admin">Dashboard</a></li>
			<li><a href="/admin/users">Users</a></li>
			<li><a href="/admin/reports">Reports</a></li>
			<li><a href="/admin/settings">Settings</a></li>
		</ul>
	</nav>

	<main class="admin-content">
		{@render children()}
	</main>
</div>

data.adminUser está disponible aquí porque el guard del layout retornó { adminUser: locals.user }. Si el guard hubiera redirigido o lanzado un error, este componente nunca se renderizaría.

Las páginas del dashboard de admin y de usuarios muestran los datos retornados por sus respectivas funciones de carga:

<!-- src/routes/admin/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<div class="admin-dashboard">
	<h1>Admin Dashboard</h1>
	<p>Welcome, {data.adminUser.name}.</p>

	<nav class="admin-quick-links">
		<a href="/admin/users">Manage Users</a>
	</nav>
</div>

<!-- src/routes/admin/users/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<div class="admin-users">
	<h1>Users</h1>
	<p>{data.pagination.total} total</p>

	<table>
		<thead>
			<tr>
				<th>ID</th>
				<th>Name</th>
				<th>Email</th>
				<th>Role</th>
			</tr>
		</thead>
		<tbody>
			{#each data.users as user (user.id)}
				<tr>
					<td>{user.id}</td>
					<td>{user.name}</td>
					<td>{user.email}</td>
					<td>{user.role}</td>
				</tr>
			{/each}
		</tbody>
	</table>

	<div class="admin-pagination">
		{#if data.pagination.page > 1}
			<a href="/admin/users?page={data.pagination.page - 1}">← Previous</a>
		{/if}
		<span>Page {data.pagination.page} of {data.pagination.totalPages}</span>
		{#if data.pagination.page < data.pagination.totalPages}
			<a href="/admin/users?page={data.pagination.page + 1}">Next →</a>
		{/if}
	</div>
</div>

La página de login establece la cookie sid directamente para simular la autenticación. Lee el parámetro de consulta returnTo para que el usuario regrese a la página que intentaba alcanzar. Después de una acción de login exitosa, redirect(303, returnTo) lo envía allí. Después del logout, redirect(303, '/') lo lleva de vuelta a la página de inicio.

<!-- src/routes/login/+page.svelte -->

<script lang="ts">
	// Two hardcoded session IDs map to the fake session store in
	// src/routes/api/session/validate/+server.ts
	const sessions = [
		{ label: 'Alice Admin (role: admin)', value: 'session-admin-123' },
		{ label: 'Bob User (role: user)', value: 'session-user-456' }
	]
</script>

<div class="login-demo">
	<h1>Demo Login</h1>
	<p>Pick an account. This sets the <code>sid</code> cookie directly — no real auth.</p>

	{#each sessions as session (session.value)}
		<form method="POST" action="/login?/login">
			<input type="hidden" name="sid" value={session.value} />
			<input
				type="hidden"
				name="returnTo"
				value={new URLSearchParams(globalThis?.location?.search ?? '').get('returnTo') ?? '/admin'}
			/>
			<button type="submit">{session.label}</button>
		</form>
	{/each}

	<form method="POST" action="/login?/logout">
		<button type="submit">Clear cookie (log out)</button>
	</form>
</div>

// src/routes/login/+page.server.ts

import type { Actions } from './$types'
import { redirect } from '@sveltejs/kit'

export const actions: Actions = {
	login: async ({ request, cookies }) => {
		const data = await request.formData()
		const sid = data.get('sid') as string
		const returnTo = (data.get('returnTo') as string) || '/admin'

		cookies.set('sid', sid, {
			path: '/',
			httpOnly: true,
			sameSite: 'lax',
			maxAge: 60 * 60 * 24 // 1 day
		})

		redirect(303, returnTo)
	},

	logout: async ({ cookies }) => {
		cookies.delete('sid', { path: '/' })
		redirect(303, '/')
	}
}

La API de sesión falsa mapea los dos IDs de sesión codificados a objetos de usuario. En una aplicación real, esto consultaría una base de datos o caché:

// src/routes/api/session/validate/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

const sessions: Record<string, { id: string; name: string; role: string }> = {
	'session-admin-123': { id: '1', name: 'Alice Admin', role: 'admin' },
	'session-user-456': { id: '2', name: 'Bob User', role: 'user' }
}

export const POST: RequestHandler = async ({ request }) => {
	const { sessionId } = await request.json()
	const user = sessions[sessionId as string] ?? null

	if (!user) {
		return json({ user: null }, { status: 401 })
	}

	return json({ user })
}

La API falsa de usuarios de admin retorna una porción paginada de usuarios codificados:

// src/routes/api/admin/users/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

const FAKE_USERS = [
	{ id: '1', name: 'Alice Admin', email: 'alice@example.com', role: 'admin' },
	{ id: '2', name: 'Bob User', email: 'bob@example.com', role: 'user' },
	{ id: '3', name: 'Carol Editor', email: 'carol@example.com', role: 'editor' },
	{ id: '4', name: 'Dave Viewer', email: 'dave@example.com', role: 'user' },
	{ id: '5', name: 'Eve Moderator', email: 'eve@example.com', role: 'moderator' }
]

export const GET: RequestHandler = async ({ url }) => {
	const page = Number(url.searchParams.get('page') ?? '1')
	const perPage = Number(url.searchParams.get('perPage') ?? '25')
	const start = (page - 1) * perPage
	const users = FAKE_USERS.slice(start, start + perPage)

	return json({ users, total: FAKE_USERS.length })
}

Errores Comunes y Anti-Patrones

Envolver redirect() en try/catch sin re-lanzar

Este es el error central del artículo. Vale la pena repetirlo porque el fallo es silencioso.

// Wrong: redirect() is caught by the catch block.
// The load function does not redirect. The page loads as if the
// guard was never there.
export const load: PageServerLoad = async ({ locals }) => {
	try {
		if (!locals.user) {
			redirect(303, '/login')
		}
		const data = await someRiskyOperation()
		return { data }
	} catch (e) {
		return { data: null }
	}
}

// Correct: redirect() is outside the try/catch,
// or re-thrown if it must appear inside one.
export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	try {
		const data = await someRiskyOperation()
		return { data }
	} catch (e) {
		return { data: null }
	}
}

Retornar null o datos vacíos en lugar de llamar a error()

// Avoid: returning null or partial data when a resource is missing.
// The page component receives null and likely throws a runtime error,
// which becomes an unexpected 500 instead of a clean 404.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		return { post: null }
	}

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

// Preferred: throw a structured error that SvelteKit can route
// to the appropriate +error.svelte file.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (response.status === 404) {
		error(404, 'Post not found')
	}

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

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

Retornar null para un recurso faltante pone la carga del estado "no encontrado" en cada componente que usa los datos. Cada componente debe verificar defensivamente si hay null antes de renderizar. Si algún componente falla en verificarlo, el error es un críptico "Cannot read properties of null" en lugar de una página 404 clara. Usar error() centraliza el manejo y produce una experiencia de usuario mucho mejor.

Usar redirect() para fallos de autorización

// Avoid: redirecting to login when the user IS authenticated but lacks permission.
// Redirecting to login implies the session is invalid, which is incorrect.
// The user will log in and be redirected back to the same forbidden page.
export const load: PageServerLoad = async ({ locals }) => {
	if (locals.user?.role !== 'admin') {
		redirect(303, '/login')
	}
	// ...
}

// Preferred: use error(403) for authorization failures.
// The user is authenticated. Their session is valid. They simply
// lack the required permission. A 403 communicates that accurately.
export const load: PageServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	if (locals.user.role !== 'admin') {
		error(403, 'You do not have permission to access this resource.')
	}
	// ...
}

La distinción entre autenticación (quién eres) y autorización (qué se te permite hacer) se mapea directamente a la elección entre redirect() y error(). La autenticación faltante requiere una redirección al login. La autorización insuficiente requiere un error 403. Confundirlos desorienta a los usuarios y hace que la aplicación sea más difícil de depurar.

Exponer detalles internos de errores a través de error()

// Wrong: passing internal details into error() where they reach the browser.
// Database errors, file paths, and internal service names are security concerns.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		const body = await response.json()
		// body.internalError might contain 'PostgreSQL: relation "posts" does not exist at line 1'
		error(500, body.internalError)
	}
	// ...
}

// Correct: pass user-safe messages to error(). Log the internal details
// server-side through handleError or direct logging.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (!response.ok) {
		// Log internally if needed through your logging service.
		// Show the user only what helps them understand what happened.
		error(500, 'Failed to load post data. Please try again.')
	}
	// ...
}

Consideraciones de Rendimiento y Escalabilidad

Los caminos de error y redirección en SvelteKit no son gratuitos desde el punto de vista del rendimiento, pero generalmente tampoco son un cuello de botella. Hay algunos patrones que vale la pena considerar a medida que tu aplicación escala.

Los guards de ruta en las cargas de layout se ejecutan para cada solicitud a cada ruta en esa sección. Una verificación de autenticación a nivel raíz que realiza una solicitud de red para validar una sesión agrega esa latencia a cada carga de página. La función handle de hooks.server.ts es un mejor lugar para la validación de sesión porque se ejecuta una vez por solicitud y puebla locals con el usuario validado, que las cargas de layout pueden leer sin hacer su propia solicitud de red. El ejemplo del layout de admin anterior usa locals.user en lugar de llamar directamente a la API de sesión, precisamente por esta razón.

El componente +error.svelte se renderiza usando el mismo pipeline de renderizado del lado del servidor que las páginas normales. Si tu página de error realiza sus propias peticiones de datos, esas peticiones se ejecutan en cada error. Mantén las páginas de error simples y autocontenidas. Deben renderizarse a partir de page.status y page.error sin realizar llamadas de API adicionales.

Para aplicaciones de alto tráfico con muchos guards de ruta, considera si tu lógica de autorización pertenece a hooks.server.ts en lugar de estar dispersa en múltiples funciones de carga de layout. Centralizar la verificación en una sola función handle significa que se ejecuta una vez, puebla locals, y cada función de carga lee desde locals sin un viaje de red de ida y vuelta. La carga del layout aún llama a error() o redirect() basándose en lo que encuentra en locals, pero la costosa validación de sesión ocurre solo una vez.

Qué Sigue

Ahora que has visto todas las formas principales de funciones de carga, servidor, universal, página, layout, y sus caminos de error y redirección, ha llegado el momento adecuado para examinar de cerca la capa de TypeScript. Los $types generados hacen más que solo tipar el argumento de la función load; rastrean la forma completa de los datos a través de layouts fusionados, proporcionan params tipados y detectan discrepancias entre lo que retorna una función de carga y lo que espera un componente. El próximo artículo, TypeScript y $types en Funciones de Carga, cubre el sistema de tipos completo alrededor de la carga de datos en SvelteKit.

Ver También

Documentación de error() de SvelteKit — referencia oficial para errores esperados e inesperados, incluyendo la lista completa de códigos de estado admitidos
Documentación de redirect() de SvelteKit — referencia oficial para redirect() incluyendo los rangos de códigos de estado válidos
Documentación de Hooks de SvelteKit — cubre handleError y el hook handle utilizado para poblar locals con datos de sesión