sveltejs/kit · error · Error

${keypath} should be a number, if specified

Error message

${keypath} should be a number, if specified

What it means

The `number` validator throws when a numeric config option receives a value that is not of type 'number'. Numeric settings such as `kit.prerender.concurrency` or `kit.prerender.pages` limits must be actual numbers; strings read from env vars or config files frequently fail this check.

Source

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

 */
function string_array(fallback) {
	return validate(fallback, (input, keypath) => {
		if (!Array.isArray(input) || input.some((value) => typeof value !== 'string')) {
			throw new Error(`${keypath} must be an array of strings, if specified`);
		}

		return input;
	});
}

/**
 * @param {number} fallback
 * @returns {Validator}
 */
function number(fallback) {
	return validate(fallback, (input, keypath) => {
		if (typeof input !== 'number') {
			throw new Error(`${keypath} should be a number, if specified`);
		}
		return input;
	});
}

/**
 * @param {boolean} fallback
 * @returns {Validator}
 */
function boolean(fallback) {
	return validate(fallback, (input, keypath) => {
		if (typeof input !== 'boolean') {
			throw new Error(`${keypath} should be true or false, if specified`);
		}
		return input;
	});
}

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Coerce with Number(): kit: { prerender: { concurrency: Number(process.env.CONCURRENCY) } }.
2. Provide a literal number in the config instead of a quoted value.
3. Remove the key to use the documented fallback.

Example fix

// before
kit: { prerender: { concurrency: process.env.CONCURRENCY } } // '4'
// after
kit: { prerender: { concurrency: Number(process.env.CONCURRENCY) || 1 } }

const c = cfg.kit?.prerender?.concurrency;
if (c !== undefined && typeof c !== 'number') throw new Error(`concurrency should be a number, got ${typeof c}`);

function isNumberOrUndefined(v) { return v === undefined || (typeof v === 'number' && !Number.isNaN(v)); }

try {
  validateOptions(cfg);
} catch (e) {
  if (String(e.message).includes('should be a number')) {
    console.error('Numeric option got non-number:', e.message, '— coerce env values with Number()');
    process.exit(1);
  } else throw e;
}

When it happens

Trigger: Setting kit.prerender.concurrency: '4' (string from process.env) or concurrency: null, then running validate_options during build/dev.

Common situations: Passing env-var strings (process.env.CONCURRENCY) directly into numeric options, or JSON-parsed values that arrived as strings.

Related errors

• ${keypath} must be an array of strings, if specified
• ${keypath} should be true or false, if specified
• ${keypath} must be a valid origin — received '${input}' whic
• Each member of ${keypath} must be either '*' or an absolute
• Unexpected option ${keypath}.${key} (did you mean config.${k

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