facebook/docusaurus · error · Error

The docs plugin found docs sharing the same id: \n

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.

Solutions

1. Rename one of the conflicting source files so the auto-computed id diverges.
2. Add an explicit `id` front matter to one of the docs to assign a distinct id.
3. If two docs are truly the same content, delete the duplicate.
4. 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
---

// 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);
}

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

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

• Invalid sidebar file at
• Invalid sidebar items collection code=
• Invalid version name
• Invalid version name
• The versions file should contain an array of version names!…

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

Appendix: 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)