{"record":{"id":"69c67d46da5af65e","repo":"facebook/docusaurus","slug":"invalid-sidebar-file-at-tomessagerelativefilepa","errorCode":null,"errorMessage":"Invalid sidebar file at \"${toMessageRelativeFilePath(sidebarFilePath)}\".\nThese legacy versioned sidebar names are not supported anymore in Docusaurus v3:\n- ${legacySidebarNames.sort().join('\\n- ')}\n\nThe sidebar names you should now use are:\n- ${legacySidebarNames.sort().map((legacyName) => legacyName.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 sidebar names are not supported anymore in Docusaurus v3:\n- (.+?)\n\nThe sidebar names 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":334,"sourceCode":"  }\n\n  // In early v2, sidebar names used to be versioned\n  // example: \"version-2.0.0-alpha.66/my-sidebar-name\"\n  // In v3 it's not the case anymore and we throw an error to explain\n  // TODO remove in Docusaurus v4\n  function checkLegacyVersionedSidebarNames({\n    versionMetadata,\n    sidebarFilePath,\n  }: {\n    versionMetadata: VersionMetadata;\n    sidebarFilePath: string;\n  }): void {\n    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);\n    const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) =>\n      sidebarName.startsWith(illegalPrefix),\n    );\n    if (legacySidebarNames.length > 0) {\n      throw new Error(\n        `Invalid sidebar file at \"${toMessageRelativeFilePath(\n          sidebarFilePath,\n        )}\".\nThese legacy versioned sidebar names are not supported anymore in Docusaurus v3:\n- ${legacySidebarNames.sort().join('\\n- ')}\n\nThe sidebar names you should now use are:\n- ${legacySidebarNames\n          .sort()\n          .map((legacyName) => legacyName.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":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts#L316-L352","documentation":"Thrown by checkLegacyVersionedSidebarNames() during v3 migration handling. In Docusaurus v2 alphas/betas, versioned sidebar keys were prefixed with the version name (e.g. 'version-2.0.0-alpha.66/my-sidebar'). v3 dropped that prefix; this guard detects sidebar names starting with `version-<versionName>/` and instructs the user to strip it. Marked TODO remove in v4.","triggerScenarios":"Upgrading a site from Docusaurus v2 to v3 whose versioned_sidebars/*.json still contains keys like 'version-1.4/sidebarName'; running `docusaurus docs:version` on a site whose sidebars were originally generated by an old v2 toolchain; importing a community starter that shipped pre-v3 versioned sidebars.","commonSituations":"Following the v2->v3 migration guide incompletely; manually editing versioned_sidebars files and preserving the legacy prefix; CI failing after a Docusaurus major bump because versioned sidebar files were never rewritten.","solutions":["In each file under versioned_sidebars/, rename every top-level key by removing the `version-<versionName>/` prefix (the error lists both the old and the correct new names).","Re-run the v3 migration codemod: `npx @docusaurus/utils@3 migrate` (or the documented v3 migration command) which rewrites sidebar names and doc ids automatically.","If you do not need the old version, remove that version entirely (versioned_docs + versioned_sidebars + its entry in versions.json).","Verify by rebuilding - the check only fires when at least one sidebar name starts with the illegal prefix."],"exampleFix":"// versioned_sidebars/version-1.4-sidebars.json - before\n{\n  \"version-1.4/tutorial\": [\n    {\"type\": \"doc\", \"id\": \"version-1.4/intro\"}\n  ]\n}\n\n// after: drop the version- prefix from the sidebar key\n{\n  \"tutorial\": [\n    {\"type\": \"doc\", \"id\": \"intro\"}\n  ]\n}","handlingStrategy":"validation","validationCode":"// Detect legacy versioned sidebar keys before building.\nconst fs = require('fs');\nconst path = require('path');\nfunction findLegacySidebarNames(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    for (const key of Object.keys(json)) {\n      if (/^version-[^/]+\\//.test(key)) legacy.push({file, key});\n    }\n  }\n  return legacy;\n}","typeGuard":"function isLegacyVersionedName(name) {\n  return /^version-[^/]+\\//.test(name);\n}","tryCatchPattern":null,"preventionTips":["Run the official v3 migration codemod when upgrading from v2.","After migration, grep versioned_sidebars/ for keys starting with `version-`.","Pin the Docusaurus major version in CI to catch breaking changes early."],"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"}