facebook/docusaurus · error · Error

The docs plugin found docs sharing the same id: \n${idMessag

Error message

The docs plugin found docs sharing the same id:
\n${idMessages}\n
Docs should have distinct ids.
In case of conflict, you can rename the docs file, or use the ${logger.code('id')} front matter to assign an explicit distinct id to each doc.

What it means

Thrown by ensureNoDuplicateDocId() during loadVersion. After all docs in a version are processed, they are grouped by their computed id; if two or more docs share an id, the build fails because doc ids must be unique (they key routing, sidebars, and cross-references). The message lists each conflicting id, how many docs share it, and the source paths involved, then suggests using the id front matter to disambiguate.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/loadVersion.ts:73

      .map(([id, duplicateDocs]) => {
        return logger.interpolate`- code=${id} found in number=${
          duplicateDocs.length
        } docs:
  - ${duplicateDocs
    .map((d) => aliasedSitePathToRelativePath(d.source))
    .join('\n  - ')}`;
      })
      .join('\n\n');

    const message = `The docs plugin found docs sharing the same id:
\n${idMessages}\n
Docs should have distinct ids.
In case of conflict, you can rename the docs file, or use the ${logger.code(
      'id',
    )} front matter to assign an explicit distinct id to each doc.
    `;

    throw new Error(message);
  }
}

async function loadVersionDocsBase({
  tagsFile,
  context,
  options,
  versionMetadata,
  env,
}: LoadVersionParams & {
  tagsFile: TagsFile | null;
}): Promise<DocMetadataBase[]> {
  const docFiles = await readVersionDocs(versionMetadata, options);
  if (docFiles.length === 0) {
    throw new Error(
      `Docs version "${
        versionMetadata.versionName
      }" has no docs! At least one doc should exist at "${path.relative(

View on GitHub (pinned to 3f483e80e3)

Solutions

Rename one of the conflicting source files so the auto-computed id diverges.
Add an explicit `id` front matter to one of the docs to assign a distinct id.
If two docs are truly the same content, delete the duplicate.
For intro.md vs intro/index.md, either rename one or set a unique id on the index.

Example fix

---
# docs/intro.md and docs/intro/index.md both compute id 'intro'

# fix: give the index an explicit id
---
# docs/intro/index.md
id: intro-overview
---

Defensive patterns

Strategy: validation

Validate before calling

// Compute ids the way Docusaurus does and flag duplicates up front.
const path = require('path');
function computeDocId(filePath) {
  const rel = path.relative('docs', filePath).replace(/\.mdx?$/, '');
  return rel.replace(/\/index$/, '').replace(/\//g, '/');
}
function findDuplicateDocIds(files) {
  const seen = {};
  for (const f of files) {
    const id = computeDocId(f);
    (seen[id] ||= []).push(f);
  }
  return Object.entries(seen).filter(([, fs]) => fs.length > 1);
}

Type guard

function docIdsAreUnique(docs) {
  const ids = docs.map((d) => d.id);
  return new Set(ids).size === ids.length;
}

Prevention

Avoid both intro.md and intro/index.md in the same directory without a unique id.
Add an explicit id front matter when filenames would collide.
On case-insensitive filesystems, keep filenames lowercase and distinct.

When it happens

Trigger: Two files compute the same id (e.g. intro.md and intro/index.md both yield id 'intro'); files with the same name in different branches of a directory that share a slug_base; explicit id front matter collisions; case-insensitive filesystems where Intro.md and intro.md resolve identically.

Common situations: Adding intro.md alongside an existing intro/ folder; mirroring docs across locales without id scoping; rename that did not update a sibling; copy-paste of a doc that kept the same id front matter.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/a99ee483c0db3c6c. Report an issue: GitHub.