Diagnosing Eleventy Pagination Issues: Missing Pages, Duplicate URLs, Raw Tags, and Stale Builds

Recognizable Condition

When working with Eleventy (@11ty/eleventy) you may notice one of the following symptoms after a build or watch run:

• No paginated files appear even though pagination front matter is present.
• Paginated files are created but URLs either repeat the same page number or omit the page segment entirely.
• The generated HTML contains raw template syntax (e.g., {{ post.title }}) instead of rendered content.
• During incremental builds (--watch) paginated pages stay unchanged after you modify the source data.

Cause / Diagnostic Table

Observed Symptom	Likely Cause	What to Look For
No paginated pages generated	Collection undefined or incorrectly named	Eleventy debug log does not show a line like Pagination: processing collection 'posts' with size 5
URLs duplicate or miss page numbers	Pagination size misconfigured or permalink misuses page variable	Permalink pattern contains hard‑coded numbers or omits {{ pagination.pageNumber }} or {{ pagination.page }}
Raw Liquid/Nunjucks syntax in output	Template engine mismatch or missing data in pagination context	File extension does not match the configured template engine, or the paginated template expects data that is not cloned into the pagination context
Stale paginated output after data changes	Eleventy cache not invalidated for pagination data	Rebuilding with --quiet produces fresh output while watch mode still serves old files

Ordered Checks

1. Confirm Eleventy recognized the pagination directive.

   npx @11ty/eleventy --debug

   Look for a log line similar to: Pagination: processing collection '' with size If the line is missing, the collection name in front matter is wrong or the collection is empty.
2. Inspect the generated _site directory. Expected layout (default permalink): _site///index.html Verify that files exist for each expected page and that they contain rendered HTML, not raw template tags.
3. Check the pagination front matter and permalink. Example of a correct configuration for a Nunjucks template:

   ---
   pagination:
     data: posts
     size: 5
     alias: post
   permalink: "posts/{{ pagination.pageNumber }}/index.html"
   ---
   {# post is the alias for each item #}
   {{ post.title }}
   {{ post.excerpt }}
   

   Ensure:
   • The key is exactly pagination (not paginate).
   • The data value matches a collection defined elsewhere (e.g., in a .eleventy.js plugin or a collection front‑matter).
   • The permalink uses either {{ pagination.pageNumber }} (Eleventy v1.0+) or {{ pagination.page }} (older versions) to produce distinct URLs.
4. Validate template engine compatibility. If you are using Liquid files (.liquid) but your project default is set to Nunjucci, Eleventy will not render the syntax. Check .eleventy.js for:

   module.exports = function(eleventyConfig) {
     eleventyConfig.setTemplateFormats(['liquid', 'njk']);
     return {};
   };
   

   Ensure the file extension matches one of the listed formats.
5. Test cache invalidation. Stop watch mode, run a clean build:

   npx @11ty/eleventy -- --clean
   

   Then start watch again and modify a data source. If the paginated output updates, the issue was cache‑related in watch mode.

Fixes Tied to Findings

• Missing collection: Rename or define the collection correctly. Example: add to .eleventy.js

  eleventyConfig.addCollection('posts', function(collectionApi) {
    return collectionApi.getFilteredByGlob('./src/posts/*.md');
  });
  

  Then use data: posts in pagination front matter.
• Incorrect pagination size or permalink: Adjust the size value to a positive integer and ensure the permalink includes the page variable. For Eleventy ≥1.0:

  permalink: "blog/{{ pagination.pageNumber }}/index.html"

  For older versions:

  permalink: "blog/{{ pagination.page }}/index.html"

• Template engine mismatch: Rename the file to match the engine or add the appropriate format to setTemplateFormats. If you prefer to keep the extension, set the engine explicitly in front matter:

  --- 
  templateEngineOverride: njk, 
  --- 

• Stale watch output: Use the --clean flag as shown above, or upgrade to Eleventy v2.0+ where watch cache invalidation for pagination data was improved. If you remain on an older version, consider disabling watch for pagination‑heavy sites and rely on manual rebuilds.

Escalation Criteria

If after performing the checks and applying the corresponding fixes you still observe any of the original symptoms, consider the following steps:

1. Verify Eleventy version (npx @11ty/eleventy --version) and compare with the version assumptions in this guide (tested with v2.0.0; behavior may differ in v0.x or v1.x).
2. Temporarily disable all custom data plugins and pagination to isolate whether a plugin returns non‑serializable data (which breaks context cloning). Re‑enable plugins one by one.
3. Run Eleventy with --dryrun to see the resolved permalink strings without writing files.
4. If the issue persists, create a minimal reproducible repository (only the problematic template, data, and .eleventy.js) and open an issue in the Eleventy GitHub repository, including the debug log output.

Limitations and Practical Verification

This guide covers the most common pagination pitfalls: missing or misnamed collections, permalink configuration errors, template‑engine mismatches, and watch‑mode cache stale‑ness. It does not exhaustively address edge cases such as asynchronous data plugins that return promises, or complex pagination filters that alter the pagination object after creation.

To confirm that a fix succeeded, rebuild the project with npx @11ty/eleventy --quiet and then:

• Check that the expected number of paginated files appears in _site.
• Open a sample file (e.g., _site/posts/2/index.html) and verify that template expressions have been replaced with actual values.
• If using watch mode, edit a data source, wait for the rebuild, and ensure the updated content appears in the paginated output.