Same 404 page appearance when returning 404 from hooks.server.ts

[hvisser]

I've noticed what resolving a route that doesn't exist yields a different 404 page vs returning a 404 response in hooks.server.ts. Ideally I want those responses to look the same, for example not to "reveal" that the 404 was caused by anything else but the route not existing in case of a route that I want to protect with special permissions. Is it possible to have sveltekit handle the request as if the route doesn't exist?

[Maxaubert]

This is expected, and it's documented: SvelteKit renders errors differently depending on where they're thrown, not on the status code.

Why they look different

• A request to a route that doesn't exist, or any error you throw with error(...) directly inside handle in hooks.server.ts (or inside a +server.js handler), gets the fallback error page (src/error.html, or SvelteKit's built-in default if you haven't added one). This never touches your +error.svelte component tree.
• An error thrown inside a load function (page or layout) bubbles up to the nearest +error.svelte above it in the route tree, same as a normal SvelteKit "framework" 404 for an unmatched route (that one also renders via the root +error.svelte).

Source, for anyone who wants to check (links point at the main branch, i.e. the code behind the currently published @sveltejs/kit 2.x, not the in-progress version-3 branch): in respond.js, calling event.resolve is wrapped in a try/catch, but if your handle hook throws before calling resolve (or you handle it as a plain error rather than calling resolve), it's caught by the outer catch in internal_respond, which calls handle_fatal_error → static_error_page, i.e. the src/error.html template:

kit/packages/kit/src/runtime/server/respond.js

Lines 412 to 427 in c6f9a78

	} catch (e) {
	if (e instanceof Redirect) {
	try {
	const response =
	is_data_request || remote_id
	? redirect_json_response(e)
	: route?.page && is_action_json_request(event)
	? action_json_redirect(e)
	: redirect_response(e.status, e.location);
	add_cookies_to_headers(response.headers, new_cookies.values());
	return response;
	} catch (err) {
	return await handle_fatal_error(event, event_state, options, err);
	}
	}
	return await handle_fatal_error(event, event_state, options, e);

kit/packages/kit/src/runtime/server/utils.js

Lines 55 to 93 in c6f9a78

	export function static_error_page(options, status, message) {
	let page = options.templates.error({ status, message: escape_html(message) });
	if (__SVELTEKIT_DEV__) {
	// inject Vite HMR client, for easier debugging
	page = page.replace('</head>', '<script type="module" src="/@vite/client"></script></head>');
	}
	return text(page, {
	headers: { 'content-type': 'text/html; charset=utf-8' },
	status
	});
	}
	/**
	* @param {import('@sveltejs/kit').RequestEvent} event
	* @param {import('types').RequestState} state
	* @param {import('types').SSROptions} options
	* @param {unknown} error
	*/
	export async function handle_fatal_error(event, state, options, error) {
	error = error instanceof HttpError ? error : coalesce_to_error(error);
	const status = get_status(error);
	const body = await handle_error_and_jsonify(event, state, options, error);
	// ideally we'd use sec-fetch-dest instead, but Safari — quelle surprise — doesn't support it
	const type = negotiate(event.request.headers.get('accept') || 'text/html', [
	'application/json',
	'text/html'
	]);
	if (event.isDataRequest || type === 'application/json') {
	return json(body, {
	status
	});
	}
	return static_error_page(options, status, body.message);
	}

Errors thrown in load, on the other hand, are caught per-node, and the code walks up the layout chain to find the closest +error.svelte, only falling back to the static page if the error happened in the root layout's load:

kit/packages/kit/src/runtime/server/page/index.js

Lines 260 to 335 in c6f9a78

	try {
	const server_data = await server_promises[i];
	const data = await load_promises[i];
	branch.push({ node, server_data, data });
	} catch (e) {
	const err = normalize_error(e);
	if (err instanceof Redirect) {
	if (state.prerendering && should_prerender_data) {
	const body = JSON.stringify({
	type: 'redirect',
	location: err.location
	});
	state.prerendering.dependencies.set(data_pathname, {
	response: text(body),
	body
	});
	}
	return redirect_response(err.status, err.location);
	}
	const status = get_status(err);
	const error = await handle_error_and_jsonify(event, event_state, options, err);
	while (i--) {
	if (page.errors[i]) {
	const index = /** @type {number} */ (page.errors[i]);
	const node = await manifest._.nodes[index]();
	let j = i;
	while (!branch[j]) j -= 1;
	data_serializer.set_max_nodes(j + 1);
	const layouts = compact(branch.slice(0, j + 1));
	const nodes = new PageNodes(layouts.map((layout) => layout.node));
	const error_branch = layouts.concat({
	node,
	data: null,
	server_data: null
	});
	return await render_response({
	event,
	event_state,
	options,
	manifest,
	state,
	resolve_opts,
	page_config: {
	ssr: nodes.ssr(),
	csr: nodes.csr()
	},
	status,
	error,
	error_components: await load_error_components(
	options,
	ssr,
	error_branch,
	page,
	manifest
	),
	branch: error_branch,
	fetched,
	data_serializer
	});
	}
	}
	// if we're still here, it means the error happened in the root layout,
	// which means we have to fall back to error.html
	return static_error_page(options, status, error.message);
	}

This is also written up in the docs under "Responses":

kit/documentation/docs/30-advanced/25-errors.md

Lines 152 to 179 in c6f9a78

	## Responses
	If an error occurs inside `handle` or inside a [`+server.js`](routing#server) request handler, SvelteKit will respond with either a fallback error page or a JSON representation of the error object, depending on the request's `Accept` headers.
	You can customise the fallback error page by adding a `src/error.html` file:
	```html
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="utf-8" />
	<title>%sveltekit.error.message%</title>
	</head>
	<body>
	<h1>My custom error page</h1>
	<p>Status: %sveltekit.status%</p>
	<p>Message: %sveltekit.error.message%</p>
	</body>
	</html>
	```
	SvelteKit will replace `%sveltekit.status%` and `%sveltekit.error.message%` with their corresponding values.
	If the error instead occurs inside a `load` function while rendering a page, SvelteKit will render the [`+error.svelte`](routing#error) component nearest to where the error occurred. If the error occurs inside a `load` function in `+layout(.server).js`, the closest error boundary in the tree is an `+error.svelte` file _above_ that layout (not next to it).
	The exception is when the error occurs inside the root `+layout.js` or `+layout.server.js`, since the root layout would ordinarily _contain_ the `+error.svelte` component. In this case, SvelteKit uses the fallback error page.
	## Type safety

The fix

Don't do the permission check (or the 404) in hooks.server.ts. Do it in the protected route's +page.server.ts / +layout.server.ts load instead:

// src/routes/admin/+layout.server.ts
import { error } from '@sveltejs/kit';

export const load = async ({ locals }) => {
  if (!locals.user?.isAdmin) {
    error(404, 'Not Found');
  }
  // ...
};

Thrown from load, this renders through the exact same +error.svelte pipeline as a genuinely unmatched route, so the response is indistinguishable. Two caveats to actually get pixel-identical output:

1. Don't add a route-group-specific +error.svelte under that protected section unless you make it render exactly like your root one, since SvelteKit picks the closest error boundary above the failing node, so a dedicated error page for that group would itself reveal that something lives there.
2. Keep doing your auth/session work as usual in handle (reading cookies, populating locals), just don't throw or return the 404 response from there yourself, only decide and throw it in load.

If you need something to run at the handle level for security reasons (e.g. cutting off unauthenticated requests before any load code executes), you can still set a flag on locals in handle and do the actual error(404) throw in the root +layout.server.js's load, but note that throwing from the root layout's load is the one case that also falls back to the static page, so keep the check one level below the root (e.g. in a group layout) if you want the styled +error.svelte.