withastro/astro · error · Error

Invalid route ${file} — parameter name must match /^[a-zA-Z0

Error message

Invalid route ${file} — parameter name must match /^[a-zA-Z0-9_$]+$/

What it means

getParts() in routing/parts.ts rejected an invalid dynamic parameter name. Identical logic to the create-manifest guard: bracketed param names must match /^(?:\.{3})?[\w$]+$/ (alphanumerics, underscore, dollar; optional ... rest prefix). Thrown as a plain Error during route parsing.

Source

Thrown at packages/astro/src/core/routing/parts.ts:17

import type { RoutePart } from '../../types/public/index.js';

// Disable eslint as we're not sure how to improve this regex yet
// eslint-disable-next-line regexp/no-super-linear-backtracking
const ROUTE_DYNAMIC_SPLIT = /\[(.+?\(.+?\)|.+?)\]/;
const ROUTE_SPREAD = /^\.{3}.+$/;

export function getParts(part: string, file: string) {
	const result: RoutePart[] = [];
	part.split(ROUTE_DYNAMIC_SPLIT).map((str, i) => {
		if (!str) return;
		const dynamic = i % 2 === 1;

		const [, content] = dynamic ? /([^(]+)$/.exec(str) || [null, null] : [null, str];

		if (!content || (dynamic && !/^(?:\.\.\.)?[\w$]+$/.test(content))) {
			throw new Error(`Invalid route ${file} — parameter name must match /^[a-zA-Z0-9_$]+$/`);
		}

		result.push({
			content,
			dynamic,
			spread: dynamic && ROUTE_SPREAD.test(content),
		});
	});

	return result;
}

View on GitHub (pinned to d081033d5f)

Solutions

1. Rename so the bracketed token matches [A-Za-z0-9_$]+, e.g. [userName].astro.
2. Keep rest params as [...name].astro with no spaces.
3. Remove any stray punctuation inside the brackets.

Example fix

// before — src/pages/users/[user-name].astro

// after — src/pages/users/[userName].astro

function isValidParamContent(content: string): boolean {
  return /^(?:\.\.\.)?[\w$]+$/.test(content);
}
// validate generated route filenames before writing them

function isValidDynamicName(name: string): boolean {
  return /^(?:\.\.\.)?[A-Za-z0-9_$]+$/.test(name);
}

When it happens

Trigger: A page file like src/pages/[user.name].astro (dot), [two-words].astro (hyphen), [spa ce].astro, or malformed brackets; an integration or content layer generating invalid route filenames.

Common situations: Naming dynamic files with non-alphanumeric characters; tooling that emits REST-style or kebab-case param names; copy-paste from other frameworks using :param-name syntax.

Related errors

• Invalid route ${file} — parameter name must match /^[a-zA-Z0
• Invalid route ${file} — parameters must be separated
• PageNumberParamNotFound
• NoMatchingStaticPathFound
• InvalidRedirectDestination

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/485899d98354ffd2. Report an issue: GitHub.