withastro/astro · error · AstroError

GetStaticPathsExpectedParams

GetStaticPathsExpectedParams

Error message

Missing or empty required `params` property on `getStaticPaths()` route.

What it means

Every getStaticPaths() entry must include a non-empty params object whose keys match the route's dynamic segments. validateGetStaticPathsResult throws AstroError code GetStaticPathsExpectedParams when params is undefined, null, or an object with zero keys.

Source

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

		});
	}

	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

Add `params: { paramName: value }` to every entry, using the exact param name from the filename.
Ensure params has at least one key and that no entry leaves params empty.
Double-check spread/rest usage that might omit params.

Example fix

// before
export async function getStaticPaths() {
  return [{ props: { post } }];
}
// after
export async function getStaticPaths() {
  return [{ params: { id: post.id }, props: { post } }];
}

Defensive patterns

Strategy: validation

Validate before calling

function assertEntriesHaveParams(entries, paramNames) {
  for (const [i, e] of entries.entries()) {
    const keys = e.params ? Object.keys(e.params) : [];
    if (!e.params || keys.length === 0) {
      throw new Error(`Entry ${i} is missing a non-empty params object`);
    }
    for (const n of paramNames) {
      if (!(n in e.params)) throw new Error(`Entry ${i} missing param '${n}'`);
    }
  }
}

Type guard

const hasNonEmptyParams = (e: unknown): boolean =>
  !!e && typeof e === 'object' &&
  'params' in e && e.params !== null && typeof e.params === 'object' &&
  Object.keys(e.params).length > 0;

Prevention

Derive required param names from the filename and assert each entry supplies them.
Avoid spreads that could omit params.
Add a small build-time test over getStaticPaths output.

When it happens

Trigger: An entry like { } (no params), { params: {} }, { params: null }, or an entry where params was destructured away; a key set whose names do not match any [param] in the filename.

Common situations: Spreading entries and accidentally dropping params; returning { props } only; mis-typing the params key.

Related errors

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