sveltejs/kit · error · Error

${keypath} should be "fail", "warn", "ignore" or a custom fu

Error message

${keypath} should be "fail", "warn", "ignore" or a custom function

What it means

The `prerender.handle` option must be either the string 'fail', 'warn', 'ignore', or a custom function `(entry) => ...`. The options validator (prerender_handler) throws when the provided value is none of these — typically a typo'd string, a wrong type, or a function placed in the wrong nesting level.

Source

Thrown at packages/kit/src/core/config/options.js:42

	sandbox: string_array(),
	'form-action': string_array(),
	'frame-ancestors': string_array(),
	'navigate-to': string_array(),
	'report-uri': string_array(),
	'report-to': string_array(),
	'require-trusted-types-for': string_array(),
	'trusted-types': string_array(),
	'upgrade-insecure-requests': boolean(false),
	'require-sri-for': string_array(),
	'block-all-mixed-content': boolean(false),
	'plugin-types': string_array(),
	referrer: string_array()
});

const prerender_handler = validate(undefined, (input, keypath) => {
	if (typeof input === 'function') return input;
	if (['fail', 'warn', 'ignore'].includes(input)) return input;
	throw new Error(`${keypath} should be "fail", "warn", "ignore" or a custom function`);
});

const options = {
	adapter: validate(undefined, (input, keypath) => {
		if (typeof input !== 'object' || !input.adapt) {
			const message = `The SvelteKit Vite plugin ${keypath} should be an object with an \`adapt\` method`;
			throw new Error(`${message}. See https://svelte.dev/docs/kit/adapters`);
		}

		return input;
	}),

	alias: deprecate(
		validate({}, (input, keypath) => {
			if (typeof input !== 'object') {
				throw new Error(`${keypath} should be an object`);
			}

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Set `kit.prerender.handle` to exactly 'fail', 'warn', or 'ignore'.
2. If custom behavior is needed, pass a function: `handle: (entry) => { ... }`.
3. Confirm the option is nested under `kit.prerender`, not `kit` directly.

Example fix

// before
kit: { prerender: { handle: 'throw' } }
// after
kit: { prerender: { handle: 'fail' } }

const handle = config.kit?.prerender?.handle;
if (handle !== undefined && typeof handle !== 'function' && !['fail', 'warn', 'ignore'].includes(handle)) {
  throw new Error('kit.prerender.handle must be "fail", "warn", "ignore" or a function');
}

/** @returns {boolean} */
function isValidPrerenderHandle(v) {
  return typeof v === 'function' || ['fail', 'warn', 'ignore'].includes(v);
}

try {
  await viteBuild();
} catch (e) {
  if (e.message.includes('should be "fail", "warn", "ignore" or a custom function')) {
    console.error('Fix kit.prerender.handle to a valid literal or function');
  }
  throw e;
}

When it happens

Trigger: validate_options walks config.kit.prerender and calls prerender_handler with an input that is not a function and not one of the literals 'fail', 'warn', 'ignore' (e.g. 'error', true, null when explicitly set, or a number).

Common situations: Typo like `handle: 'throw'` or `handle: 'log'`; copying a config where the option was renamed; passing an async wrapper incorrectly or setting the key at `kit` level instead of `kit.prerender`.

Related errors

• ${keypath} must be a valid origin (e.g. 'https://my-site.com
• Invalid isr.expiration value: ${JSON.stringify(value)} (${de
• The SvelteKit options from the Vite config must be an object
• The SvelteKit Vite plugin ${keypath} should be an object wit
• ${keypath} should be an object

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/985cb50445ce1772. Report an issue: GitHub.