{"record":{"id":"4e63c81b80cacabb","repo":"facebook/docusaurus","slug":"invalid-sidebar-file-at-tomessagerelativefilepa-4e63c8","errorCode":null,"errorMessage":"Invalid sidebar file at \"${toMessageRelativeFilePath(sidebarFilePath)}\".\nThese sidebar document ids do not exist:\n- ${invalidDocIds.sort().join('\\n- ')}\n\nAvailable document ids are:\n- ${_.uniq(allDocIds).sort().join('\\n- ')}\n","messagePattern":"Invalid sidebar file at \"(.+?)\"\\.\nThese sidebar document ids do not exist:\n- (.+?)\n\nAvailable document ids are:\n- (.+?)\n","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts","lineNumber":412,"sourceCode":"  function checkSidebarsDocIds({\n    allDocIds,\n    sidebarFilePath,\n    versionMetadata,\n  }: {\n    allDocIds: string[];\n    sidebarFilePath: string;\n    versionMetadata: VersionMetadata;\n  }) {\n    const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();\n    const invalidDocIds = _.difference(allSidebarDocIds, allDocIds);\n\n    if (invalidDocIds.length > 0) {\n      handleLegacyVersionedDocIds({\n        invalidDocIds,\n        sidebarFilePath,\n        versionMetadata,\n      });\n      throw new Error(\n        `Invalid sidebar file at \"${toMessageRelativeFilePath(\n          sidebarFilePath,\n        )}\".\nThese sidebar document ids do not exist:\n- ${invalidDocIds.sort().join('\\n- ')}\n\nAvailable document ids are:\n- ${_.uniq(allDocIds).sort().join('\\n- ')}\n`,\n      );\n    }\n  }\n\n  function getFirstLink(sidebar: Sidebar):\n    | {\n        type: 'doc';\n        id: string;\n        label: string;","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts#L394-L430","documentation":"Thrown by checkSidebarsDocIds() after the legacy-prefix guard has run. It computes the set difference between all doc ids referenced across all sidebars and the set of doc ids that actually exist (allDocIds). If any referenced id is neither a real doc id nor a legacy-prefixed one, the build fails with a list of the missing ids and all available ids.","triggerScenarios":"A sidebar item {type:'doc', id:'typo'} where the id is misspelled; deleting or renaming a doc without updating sidebars.js or versioned_sidebars; using a slug-derived id that no longer matches after a front matter id change; referencing an id from a different docs plugin instance.","commonSituations":"Refactoring docs and forgetting sidebars; stale versioned_sidebars after moving files; merge conflicts that drop a doc but keep its sidebar entry; copy-paste errors when authoring sidebars by hand.","solutions":["Compare the missing ids in the error against the available ids list and replace each typo with a real id.","Restore the deleted doc, or remove its entry from the sidebar / versioned sidebar.","If you renamed a doc, update every sidebar reference (and run `docusaurus docs:version` again for versioned sidebars).","For multi-plugin setups, confirm the id belongs to the same plugin instance (ids are scoped per docs plugin id)."],"exampleFix":"// before: id does not exist\nconst sidebars = {\n  tutorial: [{type: 'doc', id: 'itnro'}],\n};\n\n// after: match a real doc id (file intro.md)\nconst sidebars = {\n  tutorial: [{type: 'doc', id: 'intro'}],\n};","handlingStrategy":"validation","validationCode":"// Cross-check sidebar doc ids against actual doc ids before build.\nconst fg = require('fast-glob');\nconst sidebars = require('./sidebars');\nconst docIds = new Set(fg.sync(['docs/**/*.md', 'docs/**/*.mdx'])\n  .map((p) => p.replace(/^docs\\//, '').replace(/\\/(?:index)?\\.mdx?$/, '')));\nfunction collectDocIds(node, acc = []) {\n  if (!node) return acc;\n  if (Array.isArray(node)) { node.forEach((n) => collectDocIds(n, acc)); return acc; }\n  if (node.type === 'doc') acc.push(node.id);\n  if (node.items) collectDocIds(node.items, acc);\n  return acc;\n}\nconst referenced = Object.values(sidebars).flatMap((s) => collectDocIds(s));\nconst missing = referenced.filter((id) => !docIds.has(id));\nif (missing.length) throw new Error('Sidebar refs unknown docs: ' + missing.join(', '));","typeGuard":"function isKnownDocId(id, docIds) {\n  return typeof id === 'string' && docIds.has(id);\n}","tryCatchPattern":null,"preventionTips":["When deleting or renaming a doc, grep sidebars.js and versioned_sidebars/ for its id.","Use TypeScript with the official sidebar types so misconfigured ids surface in the editor.","Run `docusaurus build` in CI to catch dangling references."],"tags":["docs","sidebar","configuration","validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}