sveltejs/kit · error · Error

File extensions must be alphanumeric — saw '${extension}'

Error message

File extensions must be alphanumeric — saw '${extension}'

What it means

After checking for a leading dot, SvelteKit requires each `extensions` entry to match `/^(\.[a-z0-9]+)+$/i` — i.e. only dot-separated alphanumeric segments (`.svelte`, `.md.svelte` is fine; `.svelte-kit-files` with dashes is not). This keeps extensions usable as filename suffixes.

Source

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

			remoteFunctions: boolean(false),
			forkPreloads: boolean(false),
			handleRenderingErrors: removed()
		},
		true
	),

	extensions: validate(['.svelte'], (input, keypath) => {
		if (!Array.isArray(input) || !input.every((page) => typeof page === 'string')) {
			throw new Error(`${keypath} must be an array of strings`);
		}

		input.forEach((extension) => {
			if (extension[0] !== '.') {
				throw new Error(`Each member of ${keypath} must start with '.' — saw '${extension}'`);
			}

			if (!/^(\.[a-z0-9]+)+$/i.test(extension)) {
				throw new Error(`File extensions must be alphanumeric — saw '${extension}'`);
			}
		});

		return input;
	}),

	files: object({
		src: string('src'),
		assets: string('static'),
		hooks: object({
			client: string(null),
			server: string(null),
			universal: string(null)
		}),
		lib: removed(
			(keypath) =>
				`\`${keypath}\` has been removed. Use #lib instead of $lib: https://svelte.dev/docs/kit/$lib`
		),

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Use only alphanumeric characters after dots: `.svelte`, `.js`, `.svx`
2. Remove special characters or split into separate dot-delimited alphanumeric segments
3. If the desired filename pattern cannot be an extension, handle routing differently (e.g. rename files) instead of extending `extensions`

Example fix

// before
export default { extensions: ['.svelte', '.my-page'] };
// after
export default { extensions: ['.svelte', '.mypage'] };

const re = /^(\.[a-z0-9]+)+$/i;
for (const ext of config.extensions ?? []) {
  if (!re.test(ext)) {
    throw new Error(`Extension '${ext}' must be dot-separated alphanumeric`);
  }
}

function isAlphanumericExtension(v) {
  return Array.isArray(v) && v.every((e) => typeof e === 'string' && /^(\.[a-z0-9]+)+$/i.test(e));
}

try {
  checkExtensions(config.extensions);
} catch (e) {
  if (String(e.message).includes('must be alphanumeric')) {
    console.error('Remove special characters from extensions');
  }
  throw e;
}

When it happens

Trigger: Entries like `.s-v-e-l-t-e`, `.md!`, `.js;` or any extension containing non-alphanumeric characters after the dot.

Common situations: Trying to register multi-part or unusual suffixes with hyphens/underscores; copying glob fragments like `*.page.svelte` into the extensions list.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid isr.expiration value: ${JSON.stringify(value)} (${de
• The SvelteKit options from the Vite config must be an object
• ${keypath} should be "fail", "warn", "ignore" or a custom fu
• 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/25580a1a44fe42a8. Report an issue: GitHub.