{"record":{"id":"6935f4b367dd56e7","repo":"facebook/docusaurus","slug":"invalid-sidebar-file-at-tomessagerelativefilepa-6935f4","errorCode":null,"errorMessage":"Invalid sidebar file at \"${toMessageRelativeFilePath(sidebarFilePath)}\".\nThese legacy versioned document ids are not supported anymore in Docusaurus v3:\n- ${legacyVersionedDocIds.sort().join('\\n- ')}\n\nThe document ids you should now use are:\n- ${legacyVersionedDocIds.sort().map((legacyId) => legacyId.split('/').splice(1).join('/')).join('\\n- ')}\n\nPlease remove the \"${illegalPrefix}\" prefix from your versioned sidebar file.\nThis breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0\n","messagePattern":"Invalid sidebar file at \"(.+?)\"\\.\nThese legacy versioned document ids are not supported anymore in Docusaurus v3:\n- (.+?)\n\nThe document ids you should now use are:\n- (.+?)\n\nPlease remove the \"(.+?)\" prefix from your versioned sidebar file\\.\nThis breaking change is documented on Docusaurus v3 release notes: https://docusaurus\\.io/blog/releases/3\\.0\n","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts","lineNumber":374,"sourceCode":"  function handleLegacyVersionedDocIds({\n    invalidDocIds,\n    sidebarFilePath,\n    versionMetadata,\n  }: {\n    invalidDocIds: string[];\n    sidebarFilePath: string;\n    versionMetadata: VersionMetadata;\n  }) {\n    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);\n\n    // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix\n    // Example: \"version-1.4/my-doc-id\"\n    //\n    const legacyVersionedDocIds = invalidDocIds.filter((docId) =>\n      docId.startsWith(illegalPrefix),\n    );\n    if (legacyVersionedDocIds.length > 0) {\n      throw new Error(\n        `Invalid sidebar file at \"${toMessageRelativeFilePath(\n          sidebarFilePath,\n        )}\".\nThese legacy versioned document ids are not supported anymore in Docusaurus v3:\n- ${legacyVersionedDocIds.sort().join('\\n- ')}\n\nThe document ids you should now use are:\n- ${legacyVersionedDocIds\n          .sort()\n          .map((legacyId) => legacyId.split('/').splice(1).join('/'))\n          .join('\\n- ')}\n\nPlease remove the \"${illegalPrefix}\" prefix from your versioned sidebar file.\nThis breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0\n`,\n      );\n    }\n  }","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts#L356-L392","documentation":"Thrown by handleLegacyVersionedDocIds() as part of the v2->v3 migration guard. When checkSidebarsDocIds() finds referenced doc ids that do not exist, it first checks whether they carry the legacy `version-<versionName>/` prefix (e.g. 'version-1.4/my-doc-id'). If so, it throws this v3-specific message instead of the generic 'do not exist' error, telling the user exactly which ids to rename.","triggerScenarios":"A versioned sidebar references doc ids with the legacy versioned prefix but the actual versioned docs (post-migration) use unprefixed ids; mixed state after a partial v3 migration where sidebar files were rewritten but doc id references inside them were not; copying old versioned_sidebars content into a new version.","commonSituations":"Upgrading from v2 to v3 and only running half the migration; versioned docs were renamed by the codemod but the versioned_sidebars json was hand-edited and kept stale prefixed ids; merging branches with different migration progress.","solutions":["Edit the offending versioned_sidebars file and strip the `version-<versionName>/` prefix from each listed doc id (the message prints both the legacy and the target ids).","Run the official v3 migration codemod which rewrites both sidebar names and doc ids in one pass.","Delete the stale version (versioned_docs + versioned_sidebars + versions.json entry) if it is no longer needed.","Re-version from current using `docusaurus docs:version <name>` to regenerate clean versioned files."],"exampleFix":"// versioned_sidebars/version-1.4-sidebars.json - before\n{\n  \"tutorial\": [\n    {\"type\": \"doc\", \"id\": \"version-1.4/intro\"}\n  ]\n}\n\n// after: drop the version- prefix from the doc id\n{\n  \"tutorial\": [\n    {\"type\": \"doc\", \"id\": \"intro\"}\n  ]\n}","handlingStrategy":"validation","validationCode":"// Scan versioned_sidebars for doc ids that still carry the legacy prefix.\nconst fs = require('fs');\nconst path = require('path');\nfunction findLegacyDocIds(dir) {\n  const legacy = [];\n  for (const file of fs.readdirSync(dir)) {\n    const json = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));\n    const walk = (node) => {\n      if (!node) return;\n      if (Array.isArray(node)) return node.forEach(walk);\n      if (node.id && /^version-[^/]+\\//.test(node.id)) legacy.push({file, id: node.id});\n      if (node.items) walk(node.items);\n    };\n    walk(Object.values(json));\n  }\n  return legacy;\n}","typeGuard":"function isLegacyVersionedDocId(id) {\n  return typeof id === 'string' && /^version-[^/]+\\//.test(id);\n}","tryCatchPattern":null,"preventionTips":["Use the v3 migration codemod which rewrites both sidebar names and doc ids.","After cutting a new version, prefer `docusaurus docs:version` over hand-editing versioned files.","Add a pre-commit lint rule forbidding `version-` prefixes in versioned_sidebars JSON."],"tags":["docs","sidebar","versioning","migration","v3"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}