Fixing Duplicate Permalink Errors in Eleventy

Eleventy stops the build when two templates would write the same file:

[11ty] Problem writing Eleventy templates:
[11ty] Output conflict: multiple input files are writing to `_site/blog/c-basics/index.html`.
       Use distinct `permalink` values to resolve this conflict.
  1. ./src/blog/2021-04-c-basics.md
  2. ./src/blog/2024-02-c-sharp-basics.md
(Repeated output has been truncated…)
[11ty] DuplicatePermalinkOutputError

This is Eleventy doing you a favour: without it, one page would silently replace the other. But the error tends to appear in bursts — after a migration, after a pagination change, or when someone adds a tag that slugifies to an existing tag — and the truncated list hides how many collisions there are. This guide fixes the causes found on a 3,400-page Eleventy site after merging two blogs, and adds a dry-run check that lists every collision at once. It sits under Astro vs Eleventy for Documentation Sites.

Find Every Collision, Not Just the First

Eleventy reports collisions one batch at a time, so fixing them by rebuilding is slow. A dry run with an eleventy.after hook can list them all, because results contains every planned output path:

// eleventy.config.js
eleventyConfig.on('eleventy.after', ({ results }) => {
  const byPath = new Map();
  for (const r of results) {
    if (!r.outputPath) continue;
    byPath.set(r.outputPath, [...(byPath.get(r.outputPath) || []), r.inputPath]);
  }
  const dupes = [...byPath].filter(([, inputs]) => inputs.length > 1);
  for (const [out, inputs] of dupes) console.warn(`COLLISION ${out}\n  ${inputs.join('\n  ')}`);
});

Because Eleventy throws before eleventy.after when it finds a collision during writing, run this with --dryrun, which computes outputs without writing. On the merged site it listed 47 collisions.

Cause 1: Slugs Built From Titles

Both blogs used a directory data file that set the permalink from the title:

{ "permalink": "/blog/{{ title | slugify }}/" }

Titles like "C# Basics" and "C Basics", or "Résumé tips" and "Resume Tips", produce the same slug. After the merge, 19 pairs collided. Two fixes are possible. Derive the URL from the file name, which is unique within a directory by definition:

{ "permalink": "/blog/{{ page.fileSlug }}/" }

Or keep title-based URLs and add the year for the newer of each colliding pair. The site used page.fileSlug for new posts and kept existing URLs for the older blog's posts with explicit permalink overrides in their front matter, so that no published URL changed. Redirects for the few that did change went into the host's redirect file, as in Keeping Redirects Working After an SSG Migration.

Cause 2: Tag Pages That Collide

Tag pages were generated by paginating over collections.tagList with /tags/{{ tag | slugify }}/. The merged blogs used both "CSS" and "css", "Node.js" and "nodejs", "CI/CD" and "ci-cd". Each pair slugified to the same path. The fix was to normalise tags at the source, not at the page: a collection that lowercases and maps known aliases before building the tag list.

const ALIASES = { 'node.js': 'nodejs', 'ci/cd': 'ci-cd', 'javascript': 'js' };
const norm = (t) => ALIASES[t.toLowerCase()] ?? t.toLowerCase();
eleventyConfig.addCollection('tagList', (api) =>
  [...new Set(api.getAll().flatMap((p) => (p.data.tags || []).map(norm)))].sort());
eleventyConfig.addFilter('normTag', norm);

Post templates use normTag when linking to tag pages, so links and pages agree.

Cause 3: Pagination Page One Versus the Index

A paginated blog index used permalink: "/blog/{{ pagination.pageNumber + 1 }}/" for its pages, and a separate blog/index.njk template for the first page with a hero section. Page one of the pagination and the separate index both had valid paths — /blog/1/ and /blog/ — until someone "fixed" the permalink to skip the number on the first page, after which both wrote /blog/index.html. The clean pattern is one template that handles its own first page:

permalink: "/blog/{% if pagination.pageNumber > 0 %}page/{{ pagination.pageNumber + 1 }}/{% endif %}"

The hero section moved into the same template inside {% if pagination.pageNumber == 0 %}.

Cause 4: Files That Should Never Be Pages

Five collisions came from files that were not meant to render: two Nunjucks partials living in src/blog/ instead of _includes, a README.md in each of two content folders, and a JSON-producing template that had lost its permalink. Partials moved to _includes; READMEs went into .eleventyignore; the feed template got its explicit /feed.json permalink back. For files that need processing but no output, permalink: false is the explicit way to say so.

Cause 5: Copy-Pasted Explicit Permalinks

Three posts had been created by duplicating an existing file, and kept its permalink front matter. No automated rule could fix those; each needed a real URL. The dry-run check now runs in CI, so the next copied file fails the pull request with both input paths named.

The CI Check

The dry-run hook became a script that exits non-zero on any collision, run before the real build:

- run: npx @11ty/eleventy --dryrun --quiet
  env:
    FAIL_ON_COLLISION: '1'

It adds about 9 seconds to CI on this site and reports every collision in one run, with both input paths, rather than one batch per build attempt.

Why Collisions Cluster Around Migrations

Two of the five causes — title slugs and tag variants — barely exist on a site that has grown in one generator under one set of conventions. They appear when content from somewhere else arrives: a second blog merged in, a WordPress export converted to Markdown, a docs site absorbed into a marketing site. The incoming content was written under different conventions for case, punctuation and tagging, and the slug function maps both sets into the same, smaller space of URLs. On this site, 31 of the 47 collisions involved one post from each of the two original blogs.

That suggests running the dry-run check before a merge, not after: convert the incoming content into a branch, run --dryrun, and resolve collisions while both sets of URLs can still be mapped deliberately. It also argues for deciding URL rules up front. The merged site now documents three rules in its contributing guide — URLs come from file names, tags come from a fixed list in _data/tags.json with aliases, and explicit permalink front matter needs a reason in the pull request description — and the dry-run check enforces the first and third.

Measured Impact

Pitfalls & Rollback

• Fixing collisions one rebuild at a time. Use a dry run to list them all.
• Changing published URLs to resolve a collision. Prefer overriding the new page's permalink; redirect any old URL you must change.
• Normalising tags only in the permalink. Normalise the data so lists and pages match.
• Leaving partials in content folders. Move them to _includes or ignore them.
• Rollback: each fix is a permalink or data change in its own commit; reverting one brings back only that collision, and the CI check will report it.

Conclusion

Eleventy's duplicate permalink error protects you from silent overwrites, and its causes are few: title-derived slugs, unnormalised tags, pagination that claims the index path, files that should not render, and copied permalinks. A dry run that lists every collision turns a frustrating series of rebuilds into a single list to work through; on the merged 3,400-page site it found 47 at once.

FAQ

What does the DuplicatePermalinkOutputError mean?

Two or more templates would write to the same output file. Eleventy refuses to build rather than let one silently overwrite the other. The error names the output path and the input files involved, which is the starting point for finding which permalink rule produced the collision.

Why do two different titles produce the same slug?

Slug filters lowercase, strip punctuation and transliterate characters, so titles that differ only in case, punctuation or accents can produce identical slugs. For example, C# Basics and C Basics both become c-basics with some slug functions. Using the file path or an explicit permalink instead of a title-derived slug avoids it.

How do I stop a data file or partial from being rendered as a page?

Files inside the input directory with a template extension are rendered unless they are ignored. Put partials in the includes directory, add the path to .eleventyignore, or set permalink false in the file's front matter so it is processed but not written.

Can I make Eleventy warn instead of fail on duplicates?

Not safely. The error prevents silent data loss, where one page replaces another in the output and nobody notices until a reader reports a missing page. Fix the cause instead; the check described in this guide finds collisions in a dry run before any files are written.

Related

• Parent: Astro vs Eleventy for Documentation Sites — Eleventy's URL model and its trade-offs.
• SEO-Safe Pagination and Tag Pages — designing the paginated URLs in the first place.
• Keeping Redirects Working After an SSG Migration — redirects for changed URLs.
• Fixing Eleventy Out-of-Memory Errors on Large Collections — the other common large-site failure.
• Migrating a WordPress Export to Eleventy — where slug collisions usually first appear.