{"record":{"id":"a99ee483c0db3c6c","repo":"facebook/docusaurus","slug":"the-docs-plugin-found-docs-sharing-the-same-id-n","errorCode":null,"errorMessage":"The docs plugin found docs sharing the same id:\n\\n${idMessages}\\n\nDocs should have distinct ids.\nIn 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.\n    ","messagePattern":"The docs plugin found docs sharing the same id:\n\\\\n(.+?)\\\\n\nDocs should have distinct ids\\.\nIn case of conflict, you can rename the docs file, or use the (.+?) front matter to assign an explicit distinct id to each doc\\.\n    ","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/versions/loadVersion.ts","lineNumber":73,"sourceCode":"      .map(([id, duplicateDocs]) => {\n        return logger.interpolate`- code=${id} found in number=${\n          duplicateDocs.length\n        } docs:\n  - ${duplicateDocs\n    .map((d) => aliasedSitePathToRelativePath(d.source))\n    .join('\\n  - ')}`;\n      })\n      .join('\\n\\n');\n\n    const message = `The docs plugin found docs sharing the same id:\n\\n${idMessages}\\n\nDocs should have distinct ids.\nIn case of conflict, you can rename the docs file, or use the ${logger.code(\n      'id',\n    )} front matter to assign an explicit distinct id to each doc.\n    `;\n\n    throw new Error(message);\n  }\n}\n\nasync function loadVersionDocsBase({\n  tagsFile,\n  context,\n  options,\n  versionMetadata,\n  env,\n}: LoadVersionParams & {\n  tagsFile: TagsFile | null;\n}): Promise<DocMetadataBase[]> {\n  const docFiles = await readVersionDocs(versionMetadata, options);\n  if (docFiles.length === 0) {\n    throw new Error(\n      `Docs version \"${\n        versionMetadata.versionName\n      }\" has no docs! At least one doc should exist at \"${path.relative(","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/versions/loadVersion.ts#L55-L91","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"---\n# docs/intro.md and docs/intro/index.md both compute id 'intro'\n\n# fix: give the index an explicit id\n---\n# docs/intro/index.md\nid: intro-overview\n---","handlingStrategy":"validation","validationCode":"// Compute ids the way Docusaurus does and flag duplicates up front.\nconst path = require('path');\nfunction computeDocId(filePath) {\n  const rel = path.relative('docs', filePath).replace(/\\.mdx?$/, '');\n  return rel.replace(/\\/index$/, '').replace(/\\//g, '/');\n}\nfunction findDuplicateDocIds(files) {\n  const seen = {};\n  for (const f of files) {\n    const id = computeDocId(f);\n    (seen[id] ||= []).push(f);\n  }\n  return Object.entries(seen).filter(([, fs]) => fs.length > 1);\n}","typeGuard":"function docIdsAreUnique(docs) {\n  const ids = docs.map((d) => d.id);\n  return new Set(ids).size === ids.length;\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["docs","metadata","configuration","validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}