withastro/astro · error · AstroError

InvalidGetStaticPathsReturn

InvalidGetStaticPathsReturn

Error message

Invalid type returned by `getStaticPaths()`. Expected an `array`, got `${typeof result}`.

What it means

getStaticPaths() must return an array of objects. validateGetStaticPathsResult throws AstroError code InvalidGetStaticPathsReturn when the return value fails Array.isArray. The reported type is the JS typeof of the returned value.

Source

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

		ssr,
		route,
	}: {
		ssr: boolean;
		route: RouteData;
	},
) {
	if ((!ssr || route.prerender) && route.origin !== 'internal' && !mod.getStaticPaths) {
		throw new AstroError({
			...AstroErrorData.GetStaticPathsRequired,
			location: { file: route.component },
		});
	}
}

/** Throw error and log warnings for malformed getStaticPaths() response */
export function validateGetStaticPathsResult(result: GetStaticPathsResult, route: RouteData) {
	if (!Array.isArray(result)) {
		throw new AstroError({
			...AstroErrorData.InvalidGetStaticPathsReturn,
			message: AstroErrorData.InvalidGetStaticPathsReturn.message(typeof result),
			location: {
				file: route.component,
			},
		});
	}

	result.forEach((pathObject) => {
		if ((typeof pathObject === 'object' && Array.isArray(pathObject)) || pathObject === null) {
			throw new AstroError({
				...AstroErrorData.InvalidGetStaticPathsEntry,
				message: AstroErrorData.InvalidGetStaticPathsEntry.message(
					Array.isArray(pathObject) ? 'array' : typeof pathObject,
				),
			});
		}

View on GitHub (pinned to d081033d5f)

Solutions

1. Ensure the function ends with `return [...]` wrapping every entry in an array.
2. If you build entries with .map inside .map, flatten the result with .flat() or use .flatMap().
3. Verify with a quick Array.isArray check before returning.

Example fix

// before
export async function getStaticPaths() {
  return { params: { id: '1' } };
}
// after
export async function getStaticPaths() {
  return [{ params: { id: '1' } }];
}

function assertGSPArray(fn) {
  const result = typeof fn === 'function' ? fn() : fn;
  if (!Array.isArray(result)) {
    throw new TypeError(`getStaticPaths must return an array, got ${typeof result}`);
  }
  return result;
}

const isGSPResult = (r: unknown): r is Array<Record<string, unknown>> =>
  Array.isArray(r);

When it happens

Trigger: Returning a single object { params: {...} } instead of an array; returning undefined (e.g. forgetting to return from an async function); returning a Promise that resolves to a non-array; returning a Map or other non-array.

Common situations: Early return that drops the array; refactoring getStaticPaths and leaving a bare object; awaiting a single entry instead of a list.

Related errors

• GetStaticPathsRequired
• InvalidGetStaticPathsEntry
• GetStaticPathsExpectedParams
• [RSS] You can only glob entries within 'src/pages/' when pas
• PageNumberParamNotFound

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