withastro/astro · error · AstroError

InvalidGetStaticPathsEntry

InvalidGetStaticPathsEntry

Error message

Invalid entry returned by `getStaticPaths()`. Expected an object, got `${entryType}`.

What it means

Each element of the getStaticPaths() array must be a plain object (an entry with params). validateGetStaticPathsResult throws AstroError code InvalidGetStaticPathsEntry when an entry is itself an array (nested array) or null. The reported type is 'array' for nested arrays, otherwise typeof the entry.

Source

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

		});
	}
}

/** 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,
				),
			});
		}

		if (
			pathObject.params === undefined ||
			pathObject.params === null ||
			(pathObject.params && Object.keys(pathObject.params).length === 0)
		) {
			throw new AstroError({
				...AstroErrorData.GetStaticPathsExpectedParams,
				location: {
					file: route.component,
				},
			});

View on GitHub (pinned to d081033d5f)

Solutions

Flatten nested results with .flat() or switch the inner .map to .flatMap().
Remove any null/undefined entries before returning.
Confirm each element is a plain object literal { params, props? }.

Example fix

// before
export async function getStaticPaths() {
  return ids.map((id) => sub.map((s) => ({ params: { id, s } })));
}
// after
export async function getStaticPaths() {
  return ids.flatMap((id) => sub.map((s) => ({ params: { id, s } })));
}

Defensive patterns

Strategy: type-guard

Validate before calling

function normalizeGSP(entries) {
  const flat = entries.flat();
  for (const e of flat) {
    if (e === null || Array.isArray(e) || typeof e !== 'object') {
      throw new TypeError(`Invalid getStaticPaths entry: ${Array.isArray(e) ? 'array' : typeof e}`);
    }
  }
  return flat;
}

Type guard

const isGSPEntry = (e: unknown): e is { params: Record<string, unknown> } =>
  e !== null && typeof e === 'object' && !Array.isArray(e);

Prevention

Prefer .flatMap over nested .map to avoid arrays-of-arrays.
Filter out null/undefined before returning.
Type getStaticPaths' return as an array of entry objects.

When it happens

Trigger: Returning an array-of-arrays such as [[{params}], [{params}]] — typical when a .map inside .map is not flattened; including a null entry in the returned array.

Common situations: Using nested .map calls that produce arrays of arrays; Promise.all returning arrays of arrays; filtering that leaves nulls.

Related errors

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