facebook/docusaurus · error · Error

Invalid sidebars file. The document with id "${docId}" was u

Error message

Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
Available document ids are:
- ${Object.keys(docsById).sort().join('\n- ')}

What it means

Thrown by toSidebarsProp > getDocById when a sidebar item references a doc id that is not present in the loaded version's docs index. The message lists all available ids (sorted) so you can pick the correct one or spot the typo.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/props.ts:63

    href: permalink,
    // Front Matter data takes precedence over sidebars.json
    label: frontMatter.sidebar_label ?? item.label ?? title,
    className: frontMatter.sidebar_class_name ?? item.className,
    customProps: frontMatter.sidebar_custom_props ?? item.customProps,
    docId: id,
    unlisted,
  };
}

export function toSidebarsProp(
  loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>,
): PropSidebars {
  const docsById = createDocsByIdIndex(loadedVersion.docs);

  function getDocById(docId: string): DocMetadata {
    const docMetadata = docsById[docId];
    if (!docMetadata) {
      throw new Error(
        `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
Available document ids are:
- ${Object.keys(docsById).sort().join('\n- ')}`,
      );
    }
    return docMetadata;
  }

  const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
    const doc = getDocById(item.id);
    return toSidebarDocItemLinkProp({item, doc});
  };

  function getCategoryLinkHref(
    link: SidebarItemCategoryLink | undefined,
  ): string | undefined {
    switch (link?.type) {
      case 'doc':

View on GitHub (pinned to 3f483e80e3)

Solutions

Open sidebars.js (or the autogenerated config) and find the id printed in the message.
Replace it with one of the available ids listed in the error.
If the doc was removed, remove the sidebar entry as well.

Example fix

// before
sidebars: { docs: [{ type: 'doc', id: 'introo' }] }
// after
sidebars: { docs: [{ type: 'doc', id: 'intro' }] }

Defensive patterns

Strategy: validation

Validate before calling

const validIds = new Set(loadedVersion.docs.map(d => d.id));
function checkSidebar(item: any) {
  if (item?.type === 'doc' && !validIds.has(item.id)) {
    throw new Error(`Sidebar references unknown doc id: ${item.id}`);
  }
  (item?.items ?? []).forEach(checkSidebar);
}
sidebars.forEach(checkSidebar);

Type guard

const isKnownDocId = (id: string, docsById: Record<string, unknown>): boolean =>
  id in docsById;

Prevention

Keep sidebars.js in sync when renaming or deleting docs.
Add a CI step that validates sidebar doc ids against the docs index.

When it happens

Trigger: A sidebars configuration (sidebars.js or autogenerated sidebar) references an id that does not exist in versionMetadata docs. docsById[docId] is undefined during sidebar-to-prop conversion.

Common situations: Renaming/deleting a doc without updating sidebars.js, typo in an explicit doc id in the sidebar, or autogenerated sidebar referencing a doc whose id was changed via front matter.

Related errors

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