withastro/astro · error · AstroError

GetStaticPathsInvalidRouteParam

GetStaticPathsInvalidRouteParam

Error message

Invalid `getStaticPaths()` route parameter for `${key}`. Expected a string or undefined, received `${valueType}` (`${value}`).

What it means

validateGetStaticPathsParameter() rejected a param value whose type is not 'string' or 'undefined'. Because params are encoded into URLs, only strings (and undefined for rest-param emptiness) are allowed. Numbers, booleans, arrays, or objects are rejected with the actual value and its type.

Source

Thrown at packages/astro/src/core/routing/internal/validation.ts:8

import { AstroError, AstroErrorData } from '../../errors/index.js';

const VALID_PARAM_TYPES = ['string', 'undefined'];

/** Throws error for invalid parameter in getStaticPaths() response */
export function validateGetStaticPathsParameter([key, value]: [string, any], route: string) {
	if (!VALID_PARAM_TYPES.includes(typeof value)) {
		throw new AstroError({
			...AstroErrorData.GetStaticPathsInvalidRouteParam,
			message: AstroErrorData.GetStaticPathsInvalidRouteParam.message(key, value, typeof value),
			location: {
				file: route,
			},
		});
	}
}

View on GitHub (pinned to d081033d5f)

Solutions

Convert every param value to a string: String(value) or template literal `${value}`.
Use undefined (not null) for empty rest params.
Flatten arrays into a single string if a multi-value param is needed.

Example fix

// before
export async function getStaticPaths() {
  return posts.map(p => ({ params: { id: p.id } })); // p.id is a number
}

// after
export async function getStaticPaths() {
  return posts.map(p => ({ params: { id: String(p.id) } }));
}

Defensive patterns

Strategy: type-guard

Validate before calling

function toValidParam(value: unknown): string | undefined {
  return value === undefined ? undefined : typeof value === 'string' ? value : String(value);
}
// normalize before returning from getStaticPaths

Type guard

function isValidRouteParamValue(value: unknown): value is string | undefined {
  return value === undefined || typeof value === 'string';
}

Prevention

Always String() numeric/boolean IDs in getStaticPaths().
Type getStaticPaths params as Record<string, string | undefined>.
Use undefined (not null) for empty rest params.

When it happens

Trigger: getStaticPaths() returning { params: { id: 123 } } (number), { id: true }, { id: ['a','b'] }, or { id: {} }; passing numeric IDs from a DB without converting to string.

Common situations: Returning numeric IDs directly from data sources; spreading arrays into params; booleans from flags; forgetting String() conversion on DB results.

Related errors

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