facebook/docusaurus · error · Error

Invalid sidebar file at "${toMessageRelativeFilePath(sidebar

Error message

Invalid sidebar file at "${toMessageRelativeFilePath(sidebarFilePath)}".
These sidebar document ids do not exist:
- ${invalidDocIds.sort().join('\n- ')}

Available document ids are:
- ${_.uniq(allDocIds).sort().join('\n- ')}

What it means

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.

Source

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

  function checkSidebarsDocIds({
    allDocIds,
    sidebarFilePath,
    versionMetadata,
  }: {
    allDocIds: string[];
    sidebarFilePath: string;
    versionMetadata: VersionMetadata;
  }) {
    const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
    const invalidDocIds = _.difference(allSidebarDocIds, allDocIds);

    if (invalidDocIds.length > 0) {
      handleLegacyVersionedDocIds({
        invalidDocIds,
        sidebarFilePath,
        versionMetadata,
      });
      throw new Error(
        `Invalid sidebar file at "${toMessageRelativeFilePath(
          sidebarFilePath,
        )}".
These sidebar document ids do not exist:
- ${invalidDocIds.sort().join('\n- ')}

Available document ids are:
- ${_.uniq(allDocIds).sort().join('\n- ')}
`,
      );
    }
  }

  function getFirstLink(sidebar: Sidebar):
    | {
        type: 'doc';
        id: string;
        label: string;

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Compare the missing ids in the error against the available ids list and replace each typo with a real id.
2. Restore the deleted doc, or remove its entry from the sidebar / versioned sidebar.
3. If you renamed a doc, update every sidebar reference (and run `docusaurus docs:version` again for versioned sidebars).
4. For multi-plugin setups, confirm the id belongs to the same plugin instance (ids are scoped per docs plugin id).

Example fix

// before: id does not exist
const sidebars = {
  tutorial: [{type: 'doc', id: 'itnro'}],
};

// after: match a real doc id (file intro.md)
const sidebars = {
  tutorial: [{type: 'doc', id: 'intro'}],
};

// Cross-check sidebar doc ids against actual doc ids before build.
const fg = require('fast-glob');
const sidebars = require('./sidebars');
const docIds = new Set(fg.sync(['docs/**/*.md', 'docs/**/*.mdx'])
  .map((p) => p.replace(/^docs\//, '').replace(/\/(?:index)?\.mdx?$/, '')));
function collectDocIds(node, acc = []) {
  if (!node) return acc;
  if (Array.isArray(node)) { node.forEach((n) => collectDocIds(n, acc)); return acc; }
  if (node.type === 'doc') acc.push(node.id);
  if (node.items) collectDocIds(node.items, acc);
  return acc;
}
const referenced = Object.values(sidebars).flatMap((s) => collectDocIds(s));
const missing = referenced.filter((id) => !docIds.has(id));
if (missing.length) throw new Error('Sidebar refs unknown docs: ' + missing.join(', '));

function isKnownDocId(id, docIds) {
  return typeof id === 'string' && docIds.has(id);
}

When it happens

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

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

Related errors

• Invalid sidebar items collection code=${JSON.stringify(sideb
• Invalid sidebars file. The document with id "${docId}" was u
• Can't find any doc with ID ${docId}. Available doc IDs: - ${
• Sidebar category ${item.label} has neither any subitem nor a
• Multiple docs sidebar items produce the same translation key

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