facebook/docusaurus · error · Error

Invalid sidebar file at "${toMessageRelativeFilePath(sidebar

Error message

Invalid sidebar file at "${toMessageRelativeFilePath(sidebarFilePath)}".
These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
- ${legacySidebarNames.sort().join('\n- ')}

The sidebar names you should now use are:
- ${legacySidebarNames.sort().map((legacyName) => legacyName.split('/').splice(1).join('/')).join('\n- ')}

Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0

What it means

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.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts:334

  }

  // In early v2, sidebar names used to be versioned
  // example: "version-2.0.0-alpha.66/my-sidebar-name"
  // In v3 it's not the case anymore and we throw an error to explain
  // TODO remove in Docusaurus v4
  function checkLegacyVersionedSidebarNames({
    versionMetadata,
    sidebarFilePath,
  }: {
    versionMetadata: VersionMetadata;
    sidebarFilePath: string;
  }): void {
    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
    const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) =>
      sidebarName.startsWith(illegalPrefix),
    );
    if (legacySidebarNames.length > 0) {
      throw new Error(
        `Invalid sidebar file at "${toMessageRelativeFilePath(
          sidebarFilePath,
        )}".
These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
- ${legacySidebarNames.sort().join('\n- ')}

The sidebar names you should now use are:
- ${legacySidebarNames
          .sort()
          .map((legacyName) => legacyName.split('/').splice(1).join('/'))
          .join('\n- ')}

Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
`,
      );
    }
  }

View on GitHub (pinned to 3f483e80e3)

Solutions

1. 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).
2. 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.
3. If you do not need the old version, remove that version entirely (versioned_docs + versioned_sidebars + its entry in versions.json).
4. Verify by rebuilding - the check only fires when at least one sidebar name starts with the illegal prefix.

Example fix

// versioned_sidebars/version-1.4-sidebars.json - before
{
  "version-1.4/tutorial": [
    {"type": "doc", "id": "version-1.4/intro"}
  ]
}

// after: drop the version- prefix from the sidebar key
{
  "tutorial": [
    {"type": "doc", "id": "intro"}
  ]
}

// Detect legacy versioned sidebar keys before building.
const fs = require('fs');
const path = require('path');
function findLegacySidebarNames(dir) {
  const legacy = [];
  for (const file of fs.readdirSync(dir)) {
    const json = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
    for (const key of Object.keys(json)) {
      if (/^version-[^/]+\//.test(key)) legacy.push({file, key});
    }
  }
  return legacy;
}

function isLegacyVersionedName(name) {
  return /^version-[^/]+\//.test(name);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid sidebar file at "${toMessageRelativeFilePath(sidebar
• Can't find any sidebar with id "${sidebarId}" in version${ve
• ${pluginIdLogPrefix}: this version already exists! Use a ver
• ${pluginIdLogPrefix}: no docs found in path=${docsDir}.
• Invalid sidebars file. The document with id "${docId}" was u

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