facebook/docusaurus · error · Error

Can't find any doc with ID ${docId}. Available doc IDs: - ${

Error message

Can't find any doc with ID ${docId}.
Available doc IDs:
- ${Object.keys(docsById).join('\n- ')}

What it means

Thrown by the getDoc() helper inside DefaultSidebarItemsGenerator while it builds an autogenerated sidebar. The generator received a doc ID (from an autogenerated category index, a custom generator, or an internal lookup) that does not appear in the docsById index built from allDocs. The message echoes the offending ID and lists every available doc ID so the mismatch is visible.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts:62

type Dir = {
  [item: string]: Dir | string;
};

// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
  numberPrefixParser,
  isCategoryIndex,
  docs: allDocs,
  item: {dirName: autogenDir},
  categoriesMetadata,
}) => {
  const docsById = createDocsByIdIndex(allDocs);
  const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
    docsById[docId];
  const getDoc = (docId: string): SidebarItemsGeneratorDoc => {
    const doc = findDoc(docId);
    if (!doc) {
      throw new Error(
        `Can't find any doc with ID ${docId}.
Available doc IDs:
- ${Object.keys(docsById).join('\n- ')}`,
      );
    }
    return doc;
  };

  /**
   * Step 1. Extract the docs that are in the autogen dir.
   */
  function getAutogenDocs(): SidebarItemsGeneratorDoc[] {
    function isInAutogeneratedDir(doc: SidebarItemsGeneratorDoc) {
      return (
        // Doc at the root of the autogenerated sidebar dir
        doc.sourceDirName === autogenDir ||
        // Autogen dir is . and doc is in subfolder
        autogenDir === '.' ||

View on GitHub (pinned to 3f483e80e3)

Solutions

Read the available doc IDs printed in the error and pick the correct existing id for the referenced item.
If the referenced doc was renamed, update the file path or the id front matter so the computed id matches what the generator expects, then rebuild.
If using a custom SidebarItemsGenerator, filter its returned items against the docs array passed in (item.id must exist in docs) before returning.
Restore the missing doc file or remove the stale reference from the autogenerated category metadata (_category_.json) and re-run the build.

Example fix

// sidebars.js - custom generator referencing a stale id
async function myGenerator({docs, defaultSidebarItemsGenerator}) {
  const items = await defaultSidebarItemsGenerator({docs});
  return [...items, {type: 'doc', id: 'old-id-that-no-longer-exists'}]; // throws
}

// after: only reference ids known to exist
async function myGenerator({docs}) {
  const knownIds = new Set(docs.map((d) => d.id));
  return [{type: 'doc', id: 'intro'}, {type: 'doc', id: 'guide'}]
    .filter((item) => item.type !== 'doc' || knownIds.has(item.id));
}

Defensive patterns

Strategy: validation

Validate before calling

// Before returning items from a custom SidebarItemsGenerator,
// filter to ids that exist in the docs array passed to it.
function validateGeneratorItems(items, docs) {
  const knownIds = new Set(docs.map((d) => d.id));
  const bad = items.filter(
    (it) => it.type === 'doc' && !knownIds.has(it.id),
  );
  if (bad.length) {
    throw new Error(`Generator references unknown doc ids: ${bad.map((b) => b.id).join(', ')}`);
  }
  return items;
}

Type guard

// Narrow a sidebar item to a doc item with an existing id
function isKnownDocItem(item, knownIds) {
  return item.type === 'doc' && typeof item.id === 'string' && knownIds.has(item.id);
}

Prevention

Always derive sidebar doc references from the docs array passed to the generator rather than hardcoding ids.
After renaming or deleting a doc, grep sidebars.js and any custom generators for the old id.
Run `docusaurus start` in CI to surface sidebar/doc id mismatches before deploy.

When it happens

Trigger: A custom SidebarItemsGenerator returns an item referencing a docId that no longer exists; an autogenerated category link points to an index doc whose file was renamed or deleted; a number-prefix or slug rewrite changed the effective doc ID after the sidebar config was authored; the generator is invoked on a version whose docs folder is missing files that the sidebar still references.

Common situations: Renaming or moving a Markdown/MDX file without updating the sidebar generator output; deleting a doc but leaving it referenced in a custom generator's returned items; mixing doc IDs across versions (e.g. referencing a versioned id from the current version's generator); slug_base or id front matter edits that shift the computed id.

Related errors

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