Eleventy Pagination Diagnostic Guide: Missing, Duplicated, or Mislabeled Pages

The problem you’re seeing

A template with pagination front matter builds only one page, emits empty pages, or generates URLs like /page/undefined/. The site builds without errors, but the archive is wrong. The useful takeaway is that pagination failures are almost always data source, size/alias, or permalink problems, not a bug in Eleventy.

Recognizable conditions

• One output file instead of many. The last chunk overwrites earlier ones.
• Empty pages. Pages exist but contain no items or only the first item repeated.
• Wrong items per page or off-by-one numbering. Page 1 shows items 11-20, or page numbers display as 0,1,2 when you expect 1,2,3.
• URLs with undefined. Permalink contains a token that was never populated, e.g., /page/undefined/.

Cause / diagnostic table

Symptom	Most likely cause	Why it happens
One output file	Static permalink or data key wrong	Every pagination chunk writes to the same path, or pagination runs over undefined/single item.
Empty pages	Collection filtered after pagination or reversed data	Data source is empty at build time, or items are removed by a filter before rendering.
Wrong item on page / duplicated first page	Alias confusion or pageNumber vs pageIndex mix-up	size: 1 with alias changes exposure; pageNumber is zero-based.
URLs with undefined	Dynamic permalink missing pagination token	Permalink does not reference pagination.pageNumber or pagination.href.

Ordered checks

1. Confirm the data source exists

Run from the project root with Node installed and write access to the project folder:

npx @11ty/eleventy --debug

Expected check: debug output lists collections and data files. In the template, temporarily dump the source:

{# debug dump #}
{{ pagination.data | dump }}

Risk: dumping large collections clutters output. Remove after check.

2. Verify size and alias

Open the paginated template front matter. A minimal working shape is:

---
pagination:
  data: collections.posts
  size: 10
  alias: posts
permalink: "/posts/page/{{ pagination.pageNumber }}/"
---

Check that data points to an existing collection or global data file. If size is omitted, Eleventy defaults to a single page. If size: 1 is used, pagination.items contains one item per page and the alias is the only way to reference it in the template.

3. Inspect the generated _site structure

After a clean build, list output:

ls -R _site/posts

Expected check: number of directories equals ceil(items / size). With 25 items and size 10 you expect three outputs. Missing directories indicate a static permalink or wrong data.

4. Test the permalink pattern in isolation

Permalink must be dynamic. A static value like permalink: "/posts/" causes overwrite. Verify the template uses pagination.pageNumber or pagination.href. Nunjucks example:

permalink: "/posts/{{ pagination.pageNumber }}/"

Note: pagination.pageNumber is zero-based. Display logic often needs +1.

Fixes tied to findings

One output file

Make permalink dynamic and ensure data is valid. Change a static permalink to include pagination.pageNumber. Confirm the data key matches a collection name exactly. Paginating over collections.all can include the paginated template itself, creating self-reference. Use a specific collection.

Empty pages

Confirm the collection is populated at build time. Collections are built after data files are read. If you filter the collection in .eleventy.js, ensure the filter runs before pagination is evaluated. Remove reverse or before/after callbacks temporarily to test.

Wrong items / off-by-one

Dump pagination metadata in the template:

PageNumber: {{ pagination.pageNumber }}

PageIndex: {{ pagination.pageIndex }}

Items length: {{ pagination.items.length }}

If you need human numbering, use {{ pagination.pageNumber + 1 }}. If using alias, reference the alias variable, not pagination.items, in the loop.

URLs with undefined

Replace undefined tokens with pagination.pageNumber or use pagination.href for links. Ensure the permalink string is quoted correctly in YAML front matter.

Limitations and verification

Eleventy 3.x defaults to ESM and changed some config behaviors. Pagination front matter is stable, but config-file differences can affect when data is loaded. Incremental builds can retain stale pages. Clean build before verifying.

Practical verification: create a minimal test with a data file of 25 items, size: 10, dynamic permalink, and confirm _site contains exactly three output directories with correct items. Run npx @11ty/eleventy --serve --incremental and edit the data source to confirm pages regenerate without stale output.

When to escalate

Escalate when pagination interacts with reverse, before/after callbacks, or custom collections, since ordering bugs there are subtle. Reproduce in a minimal repo with one collection, one template, and static data before filing an issue. Include Eleventy version, config file type, and the front matter used.