sveltejs/kit · error · Error

${keypath} must be an array of strings, if specified

Error message

${keypath} must be an array of strings, if specified

What it means

The `string_array` validator requires that, when an option is provided, its value is an array containing only strings. It is used for list-shaped kit options (e.g. `kit.alias`-adjacent lists, CSP-like directives lists, `moduleExtensions` style options). Passing anything else — or an array with mixed types — throws this error.

Source

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

	return validate(fallback, (input, keypath) => {
		assert_string(input, keypath);

		if (!allow_empty && input === '') {
			throw new Error(`${keypath} cannot be empty`);
		}

		return input;
	});
}

/**
 * @param {string[] | undefined} [fallback]
 * @returns {Validator}
 */
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;
	});
}

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Wrap the value in an array: someOption: ['*.example.com'].
2. Filter or coerce array members to strings before assigning.
3. Omit the option (leave undefined) if you don't need it — the error only fires when it is specified.

Example fix

// before
kit: { csp: { styleSrc: 'self' } }
// after
kit: { csp: { styleSrc: ['self'] } }

const v = cfg.kit?.csp?.styleSrc;
if (v !== undefined && !(Array.isArray(v) && v.every((x) => typeof x === 'string'))) {
  throw new Error('csp.styleSrc must be an array of strings');
}

function isStringArrayOrUndefined(v) { return v === undefined || (Array.isArray(v) && v.every((x) => typeof x === 'string')); }

try {
  validateOptions(cfg);
} catch (e) {
  if (String(e.message).includes('must be an array of strings, if specified')) {
    console.error('List-shaped option has wrong type:', e.message);
    process.exit(1);
  } else throw e;
}

When it happens

Trigger: Assigning a single string instead of an array (e.g. someOption: '*.example.com'), or an array containing non-strings (numbers, booleans, null), to any option validated by string_array in options.js.

Common situations: Hand-editing config and forgetting array brackets, or building lists programmatically where undefined/null entries sneak in from optional lookups.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• ${keypath} should be a number, 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/23129cc6ec0bb80b. Report an issue: GitHub.