facebook/docusaurus · error · Error

Can't find any sidebar with id "${sidebarId}" in version${ve

Error message

Can't find any sidebar with id "${sidebarId}" in version${versions.length > 1 ? 's' : ''} ${versions.map((version) => version.name).join(', ')}".
Available sidebar ids are:
- ${allSidebars.map((entry) => entry[0]).join('\n- ')}

What it means

Thrown by useLayoutDocsSidebar() when no sidebar with the given sidebarId exists in ANY of the candidate versions. It collects all sidebars across versions (useDocsVersionCandidates: active + preferred + latest), and if none matches sidebarId, throws a message listing every available sidebar id so you can pick a valid one. This hook is designed for layout components (navbar items) that must resolve a sidebar even on non-doc pages, hence the multi-version search. The useMemo recomputes when sidebarId or the candidate versions change.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/client/docsUtils.tsx:333

 * be ambiguous. This hook would always return a sidebar to be linked to. See
 * also {@link useDocsVersionCandidates} for how this selection is done.
 *
 * @throws This hook throws if a sidebar with said ID is not found.
 */
export function useLayoutDocsSidebar(
  sidebarId: string,
  docsPluginId?: string,
): GlobalSidebar {
  const versions = useDocsVersionCandidates(docsPluginId);
  return useMemo(() => {
    const allSidebars = versions.flatMap((version) =>
      version.sidebars ? Object.entries(version.sidebars) : [],
    );
    const sidebarEntry = allSidebars.find(
      (sidebar) => sidebar[0] === sidebarId,
    );
    if (!sidebarEntry) {
      throw new Error(
        `Can't find any sidebar with id "${sidebarId}" in version${
          versions.length > 1 ? 's' : ''
        } ${versions.map((version) => version.name).join(', ')}".
Available sidebar ids are:
- ${allSidebars.map((entry) => entry[0]).join('\n- ')}`,
      );
    }
    return sidebarEntry[1];
  }, [sidebarId, versions]);
}

/**
 * The layout components, like navbar items, must be able to work on all pages,
 * even on non-doc ones where there's no version context, so a doc ID could be
 * ambiguous. This hook would always return a doc to be linked to. See also
 * {@link useDocsVersionCandidates} for how this selection is done.
 *
 * @throws This hook throws if a doc with said ID is not found.

View on GitHub (pinned to 3f483e80e3)

Solutions

  1. Read the 'Available sidebar ids' list in the error and use one of those exact ids.
  2. Open sidebars.js (or the versioned sidebars) and confirm the sidebar id spelling matches the config reference exactly.
  3. If the sidebar lives in a different docs plugin, pass the correct docsPluginId as the second argument to useLayoutDocsSidebar.
  4. If the id was renamed, update all navbar/layout references to the new id.

Example fix

// before
// docusaurus.config.ts
navbar: [{ type: 'doc', sidebarId: 'tutorials', ... }]
// sidebars.js
export default { learn: [{type: 'autogenerated', dirName: '.'}] };
// after: align the id
navbar: [{ type: 'doc', sidebarId: 'learn', ... }]
Defensive patterns

Strategy: validation

Validate before calling

import {useDocsVersionCandidates} from '@docusaurus/plugin-content-docs/client';

function useKnownSidebarId(sidebarId: string, docsPluginId?: string) {
  const versions = useDocsVersionCandidates(docsPluginId);
  const allIds = versions.flatMap((v) =>
    v.sidebars ? Object.keys(v.sidebars) : [],
  );
  if (!allIds.includes(sidebarId)) {
    return {valid: false, available: allIds} as const;
  }
  return {valid: true, available: allIds} as const;
}
// const check = useKnownSidebarId('tutorial'); if (!check.valid) return null;

Type guard

const isKnownSidebarId = (
  id: string,
  versions: {sidebars?: Record<string, unknown>}[],
): boolean => versions.some((v) => v.sidebars && id in v.sidebars);

Prevention

When it happens

Trigger: A navbar item / layout config references a sidebar id (e.g. `{type: 'doc', sidebarId: 'tutorial'})` that was never declared in sidebars.js, was renamed, or only existed in a removed version. The throw happens at render time inside useMemo.

Common situations: Renaming a sidebar id in sidebars.js but leaving stale references in docusaurus.config.ts navbar items; pointing at a sidebar id that lives in a different docs plugin id (docsPluginId mismatch); deleting a versioned sidebar while config still references it.

Related errors

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