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 ejecución críptico, o peor aún, servir contenido protegido silenciosamente.

SvelteKit te proporciona dos funciones para manejar estas situaciones de forma 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 funcionan de la misma manera: las llamas y detienen inmediatamente la función load lanzando internamente. No necesitas escribir throw tú mismo.

También hay 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 los captura 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 try/catch que los envuelva interceptará accidentalmente la señal antes de que SvelteKit la vea. Ese único error (envolver una redirección en un try/catch) es la razón por la que los guardias de ruta dejan de funcionar silenciosamente en producción. Este artículo cubre los tres caminos, en el orden en que probablemente los necesites.

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 explique 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 ejecución que SvelteKit capturaría como un error inesperado en lugar de uno controlado.

En SvelteKit tenemos dos herramientas para el fallo controlado: error() y redirect(), ambas importadas desde @sveltejs/kit. No son funciones utilitarias 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 apropiado del framework.

También hay una tercera categoría: errores que no tenías la intención de lanzar en absoluto, un timeout de red, falla al parsear JSON, una desreferencia de null, etcétera. 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 que se muestra al usuario es deliberadamente mínima, y los detalles van a tu sistema de logging en su lugar.

Los Cuatro Resultados

Cada 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, que es el fallo silencioso del 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 carece del permiso requerido. Un 503 porque una dependencia está caída y quieres comunicarlo claramente. Estos son errores que eliges lanzar.

La función error() recibe 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 las funciones load:

Código	Nombre	Cuándo usar
`400`	Bad Request	Los parámetros de consulta o de ruta tienen un formato incorrecto 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 ha sido 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() es intencionalmente visible para el 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 trazas de pila, 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 tu aplicación define. SvelteKit pasa el objeto de mensaje completo a 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 recorre 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 toda la jerarquía, SvelteKit recurre a su página de error integrada.

Esta jerarquía es intencional. Un 404 en una entrada de blog no necesita verse igual que un 404 en la página de pago. Al colocar archivos +error.svelte en diferentes niveles, puedes dar a secciones de tu aplicación su propia presentación de errores, mientras sigues teniendo 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 layouts: el archivo +error.svelte se renderiza dentro del layout más cercano que también tiene su propio +error.svelte definido en él o por encima. No se renderiza de manera aislada. Esto significa que la navegación, las fuentes y los estilos globales del layout raíz todavía están 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() recibe 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 las 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 el envío de formularios.

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

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

El estado 307 significa "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ó vía 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 permanentemente y debe actualizarse en los índices de los motores de búsqueda.

Código	Nombre	Método	Duración	Cuándo usar
`301`	Moved Permanently	Solo GET	Permanente	La URL ha cambiado para siempre. Los navegadores y motores de búsqueda cachean esto — 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	Opción predeterminada para redirecciones de autenticación. Envía usuarios no autenticados al login. Siempre resulta en un GET sin importar el método original.
`307`	Temporary Redirect	Preserva el método	Temporal	Usar al redirigir 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 ruta en funciones load, elige 303. Es inequívoco, seguro para navegadores, y tiene la semántica correcta para las 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 ejecución 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 ocurrido.

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 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')
	}
}

isRedirect type guard

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')
	}
}

isHttpError type guard

El type guard isHttpError sirve el mismo propósito para instancias de error(). Si estás capturando todos los errores en una función load y quieres permitir que las llamadas esperadas a error() pasen, vuelve a lanzarlas 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 debe envolver las líneas de código específicas que pueden lanzar errores inesperados, como fetch y response.json(). De esta manera evitas el riesgo de interceptar accidentalmente una redirección o un 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 ruta y el manejo de errores de una manera que solo aparece 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, un new Error(...) lanzado desde una función utilitaria, etc. Estos son errores que no tenías la 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.

Esta mensajería genérica 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 los 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, permitiéndote 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 indicarle al usuario que el contenido no fue encontrado y ofrecer un camino a seguir.
Los errores inesperados deben ser honestos sobre el fallo 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 login, URL de retorno preservada
Cookie `sid` con `role: user`	Autenticado, rol incorrecto	`error(403, ...)` — el `+error.svelte` de admin se renderiza con el mensaje 403
Cookie `sid` con `role: admin`	Autenticado, rol correcto	La carga tiene éxito, 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` — activa 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 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, cargas de layout, cargas 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 correcto 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 suprimida. Ejecutarlo 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 lee. La función de carga puede entonces llamar a redirect() o error() limpiamente, sin ningún try/catch cerca de ellos.

// 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. Como App.Locals lo declara como { ... } | null, TypeScript se encargará de 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() o 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 redirect() y error() aparecen juntos

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 — verificaciones de guard primero, operaciones riesgosas (si las hay) después, en un try/catch separado que no rodea 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. Para cuando los archivos +page.server.ts bajo /admin se ejecutan, locals.user tiene garantizado existir y tener 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 de obtención de datos específicos 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 hacia arriba 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 el shell 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 el shell de navegación 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 una excepción, 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 aterrice de vuelta en la página que intentaba alcanzar. Después de una acción de login exitosa, redirect(303, returnTo) los envía allí. Después del logout, redirect(303, '/') los 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 es 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 clara página 404. 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é tienes permitido hacer) se mapea directamente a la elección entre redirect() y error(). La falta de autenticación requiere una redirección al login. La autorización insuficiente requiere un error 403. Confundirlos desorienta a los usuarios y hace la aplicación más difícil de depurar.

Exponer detalles internos de error 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 tampoco son generalmente un cuello de botella. Algunos patrones 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 añade 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, exactamente 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 hace sus propias solicitudes de datos, esas solicitudes 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 adicionales a la API.

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 de locals sin una ida y vuelta de red. La carga de layout todavía 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, server, universal, page, layout, y sus caminos de error y redirección, ha llegado el momento correcto de 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 los layouts fusionados, proveen 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 and $types in Load Functions, 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 soportados
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