{"record":{"id":"6eef103dbc8fea50","repo":"withastro/astro","slug":"pagenumberparamnotfound","errorCode":"PageNumberParamNotFound","errorMessage":"[paginate()] page number param `${paramName}` not found in your filepath.","messagePattern":"\\[paginate\\(\\)\\] page number param `(.+?)` not found in your filepath\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/render/paginate.ts","lineNumber":36,"sourceCode":"): (...args: Parameters<PaginateFunction>) => ReturnType<PaginateFunction> {\n\treturn function paginateUtility(\n\t\tdata: readonly any[],\n\t\targs: PaginateOptions<Props, Params> = {},\n\t): ReturnType<PaginateFunction> {\n\t\tconst generate = getRouteGenerator(routeMatch.segments, trailingSlash);\n\t\tlet { pageSize: _pageSize, params: _params, props: _props, format: _format } = args;\n\t\tconst pageSize = _pageSize || 10;\n\t\tconst paramName = 'page';\n\t\tconst additionalParams = _params || {};\n\t\tconst additionalProps = _props || {};\n\t\tconst formatUrl = _format || ((url: string) => url);\n\t\tlet includesFirstPageNumber: boolean;\n\t\tif (routeMatch.params.includes(`...${paramName}`)) {\n\t\t\tincludesFirstPageNumber = false;\n\t\t} else if (routeMatch.params.includes(`${paramName}`)) {\n\t\t\tincludesFirstPageNumber = true;\n\t\t} else {\n\t\t\tthrow new AstroError({\n\t\t\t\t...AstroErrorData.PageNumberParamNotFound,\n\t\t\t\tmessage: AstroErrorData.PageNumberParamNotFound.message(paramName),\n\t\t\t});\n\t\t}\n\t\tconst lastPage = Math.max(1, Math.ceil(data.length / pageSize));\n\n\t\tconst result = [...Array(lastPage).keys()].map((num) => {\n\t\t\tconst pageNum = num + 1;\n\t\t\tconst start = pageSize === Number.POSITIVE_INFINITY ? 0 : (pageNum - 1) * pageSize; // currentPage is 1-indexed\n\t\t\tconst end = Math.min(start + pageSize, data.length);\n\t\t\tconst params = {\n\t\t\t\t...additionalParams,\n\t\t\t\t[paramName]: includesFirstPageNumber || pageNum > 1 ? String(pageNum) : undefined,\n\t\t\t};\n\t\t\tconst current = formatUrl(addRouteBase(generate({ ...params }), base));\n\t\t\tconst next =\n\t\t\t\tpageNum === lastPage\n\t\t\t\t\t? undefined","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/core/render/paginate.ts#L18-L54","documentation":"`paginate()` is the helper passed to `getStaticPaths()` for pagination; it generates one entry per page using a fixed param named `page`. Each generated path needs somewhere to put that number, so the route's params must contain either `page` (via a `[page].astro` file) or `...page` (via `[...page].astro`, which folds page 1 into the base path). If the matched route declares neither, Astro throws `PageNumberParamNotFound`.","triggerScenarios":"Calling `paginate(data)` inside `getStaticPaths()` of a page whose filename has no page param, e.g. `src/pages/products.astro`; misspelling the param in the filename (`[...pages].astro`, `[pagenum].astro`) so the literal `page`/`...page` param never exists; restructuring pages and dropping the `[page]` segment.","commonSituations":"First attempt at paginating a listing page before renaming the file; renaming `[page].astro` during a refactor and forgetting getStaticPaths still paginates; copy-pasting a paginated component into a non-dynamic route.","solutions":["Rename the file to include the param: `src/pages/products/[page].astro`","Use the spread form `src/pages/products/[...page].astro` when page 1 should live at the base URL `/products`","Spell the param exactly `page` — `paginate()` does not accept a custom param name"],"exampleFix":"# before\nsrc/pages/products.astro   # exports getStaticPaths using paginate()\n\n# after\nsrc/pages/products/[page].astro   # param must be named exactly `page`\n# (or products/[...page].astro so page 1 lives at /products)","handlingStrategy":"validation","validationCode":"# CI guard: paginate() must live in a file whose name contains [page] or [...page]\ngrep -rl 'paginate(' src/pages --include='*.astro' | grep -v '\\[\\.\\.\\.page\\]\\|\\[page\\]' && { echo 'paginate() used without a [page] param'; exit 1; } || true","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Name paginated routes `[page].astro` (or `[...page].astro`) before writing getStaticPaths","The param name is fixed to `page` — never `[p]`, `[pagenum]`, or `[...pages]`","Add the grep guard above to CI so renames fail fast"],"tags":["paginate","getstaticpaths","file-based-routing","build"],"backgroundTag":"pagination-route-param-missing","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}