facebook/docusaurus · error · Error

Doc with ID ${docId} wants to display sidebar ${sidebarName}

Error message

Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist

What it means

Thrown by getDocNavigation() inside createSidebarsUtils. When computing prev/next navigation for a doc, the plugin resolves which sidebar to display: either from the doc's displayed_sidebar front matter (displayedSidebar) or from the reverse doc-id->sidebar-name map. If the resolved sidebarName has no entry in sidebarNameToNavigationItems (i.e. no sidebar with that name was registered), the build aborts.

Source

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

    docId,
    displayedSidebar,
    unlistedIds,
  }: {
    docId: string;
    displayedSidebar: string | null | undefined;
    unlistedIds: Set<string>;
  }): SidebarNavigation {
    const sidebarName =
      displayedSidebar === undefined
        ? getSidebarNameByDocId(docId)
        : displayedSidebar;

    if (!sidebarName) {
      return emptySidebarNavigation();
    }
    let navigationItems = sidebarNameToNavigationItems[sidebarName];
    if (!navigationItems) {
      throw new Error(
        `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
      );
    }

    // Filter unlisted items from navigation
    navigationItems = navigationItems.filter((item) => {
      if (item.type === 'doc' && unlistedIds.has(item.id)) {
        return false;
      }
      if (
        item.type === 'category' &&
        item.link.type === 'doc' &&
        unlistedIds.has(item.link.id)
      ) {
        return false;
      }
      return true;
    });

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Open sidebars.js and confirm a sidebar with exactly the name in displayed_sidebar is exported; fix the front matter to match.
2. Remove the displayed_sidebar front matter entirely so the plugin auto-resolves the sidebar from the doc id.
3. If you meant to point at a different docs plugin instance, correct the plugin id / sidebar name accordingly.
4. Trim whitespace and verify casing - sidebar names are case-sensitive identifiers, not labels.

Example fix

---
# before
id: my-doc
displayed_sidebar: oldName
---

---
# after: match the exported sidebar key in sidebars.js
id: my-doc
displayed_sidebar: tutorial
---

// Before building, verify every doc's displayed_sidebar matches an exported sidebar.
const sidebarNames = new Set(Object.keys(require('./sidebars')));
function validateDisplayedSidebar(frontMatter, docPath) {
  if (frontMatter.displayed_sidebar && !sidebarNames.has(frontMatter.displayed_sidebar)) {
    throw new Error(`${docPath}: displayed_sidebar '${frontMatter.displayed_sidebar}' is not a known sidebar (${[...sidebarNames].join(', ')})`);
  }
}

function isValidDisplayedSidebar(value, sidebarNames) {
  return typeof value === 'string' && sidebarNames.has(value);
}

When it happens

Trigger: A doc has front matter `displayed_sidebar: foo` but no sidebar named foo is exported from sidebars.js; a versioned sidebar was renamed and the doc's front matter still references the old name; the displayed_sidebar value has a typo or trailing whitespace; multiple docs plugins share ids but a doc points at a sidebar owned by a different plugin instance.

Common situations: Renaming a sidebar key in sidebars.js without updating docs that pin displayed_sidebar; copy-pasting front matter between docs and forgetting to adjust the sidebar name; using a localized or versioned name that does not match the current sidebar export.

Related errors

• Error when loading ${doc.id} in ${doc.sourceDirName}: the pa
• Can't create navigation link: no doc found with id=${docId}
• Document id "${baseID}" cannot include slash.
• Invalid sidebars file. The document with id "${docId}" was u
• Can't find any doc with ID ${docId}. Available doc IDs: - ${

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