facebook/docusaurus · error · Error

Invalid sidebar file at "${toMessageRelativeFilePath(sidebar

Error message

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

The document ids you should now use are:
- ${legacyVersionedDocIds.sort().map((legacyId) => legacyId.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 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.

Source

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

  function handleLegacyVersionedDocIds({
    invalidDocIds,
    sidebarFilePath,
    versionMetadata,
  }: {
    invalidDocIds: string[];
    sidebarFilePath: string;
    versionMetadata: VersionMetadata;
  }) {
    const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);

    // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
    // Example: "version-1.4/my-doc-id"
    //
    const legacyVersionedDocIds = invalidDocIds.filter((docId) =>
      docId.startsWith(illegalPrefix),
    );
    if (legacyVersionedDocIds.length > 0) {
      throw new Error(
        `Invalid sidebar file at "${toMessageRelativeFilePath(
          sidebarFilePath,
        )}".
These legacy versioned document ids are not supported anymore in Docusaurus v3:
- ${legacyVersionedDocIds.sort().join('\n- ')}

The document ids you should now use are:
- ${legacyVersionedDocIds
          .sort()
          .map((legacyId) => legacyId.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

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.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

// Scan versioned_sidebars for doc ids that still carry the legacy prefix.
const fs = require('fs');
const path = require('path');
function findLegacyDocIds(dir) {
  const legacy = [];
  for (const file of fs.readdirSync(dir)) {
    const json = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
    const walk = (node) => {
      if (!node) return;
      if (Array.isArray(node)) return node.forEach(walk);
      if (node.id && /^version-[^/]+\//.test(node.id)) legacy.push({file, id: node.id});
      if (node.items) walk(node.items);
    };
    walk(Object.values(json));
  }
  return legacy;
}

Type guard

function isLegacyVersionedDocId(id) {
  return typeof id === 'string' && /^version-[^/]+\//.test(id);
}

Prevention

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.

When it happens

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

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

Related errors

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