withastro/astro · error · Error

Invalid route ${file} — rest parameter must be a standalone

Error message

Invalid route ${file} — rest parameter must be a standalone segment

What it means

A rest parameter [...rest] in an .astro route must occupy the entire segment; it cannot be combined with other characters in the same filename. validateSegment rejects names matching /.+[...x]/ or /[...x].+/ when the file ends with .astro. (This restriction is specific to .astro files.)

Source

Thrown at packages/astro/src/core/routing/segment.ts:14

export function validateSegment(segment: string, file = '') {
	if (!file) file = segment;

	if (segment.includes('][')) {
		throw new Error(`Invalid route ${file} \u2014 parameters must be separated`);
	}
	if (countOccurrences('[', segment) !== countOccurrences(']', segment)) {
		throw new Error(`Invalid route ${file} \u2014 brackets are unbalanced`);
	}
	if (
		(/.+\[\.\.\.[^\]]+\]/.test(segment) || /\[\.\.\.[^\]]+\].+/.test(segment)) &&
		file.endsWith('.astro')
	) {
		throw new Error(`Invalid route ${file} \u2014 rest parameter must be a standalone segment`);
	}
}

function countOccurrences(needle: string, haystack: string) {
	let count = 0;
	for (const hay of haystack) {
		if (hay === needle) count += 1;
	}
	return count;
}

View on GitHub (pinned to d081033d5f)

Solutions

Make the rest parameter its own standalone segment via a folder/file, e.g. src/pages/post/[...slug].astro.
Remove any literal text adjacent to the [...rest] token.
If you need a prefix, nest directories instead of concatenating text to the rest parameter.

Example fix

// before
src/pages/post-[...slug].astro
// after
src/pages/post/[...slug].astro

Defensive patterns

Strategy: validation

Validate before calling

function isStandaloneRestSegment(fileName) {
  if (!fileName.endsWith('.astro')) return true;
  return !(/.+\[\.\.\.[^\]]+\]/.test(fileName) || /\[\.\.\.[^\]]+\].+/.test(fileName));
}
for (const f of routeFiles) {
  if (!isStandaloneRestSegment(f)) throw new Error(`Rest param must be standalone in ${f}`);
}

Type guard

const isStandaloneRest = (name: string): boolean =>
  !(name.endsWith('.astro') && (/.+\[\.\.\.[^\]]+\]/.test(name) || /\[\.\.\.[^\]]+\].+/.test(name)));

Prevention

Keep catch-all [...rest] as the only text in its filename.
Use nested folders to add prefixes instead of text in the filename.
Remember the rule applies to .astro files specifically.

When it happens

Trigger: An .astro filename where a catch-all [...slug] is adjacent to literal text, e.g. src/pages/post-[...slug].astro, src/pages/[...path]index.astro, or src/pages/blog[...rest].astro.

Common situations: Trying to prefix or suffix a catch-all route; migrating a wildcard and leaving text around the rest parameter; using [...rest] alongside a static word.

Related errors

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