{"record":{"id":"842e01eb9605c5a7","repo":"facebook/docusaurus","slug":"can-t-create-navigation-link-no-doc-found-with-id","errorCode":null,"errorMessage":"Can't create navigation link: no doc found with id=${docId}","messagePattern":"Can't create navigation link: no doc found with id=(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts","lineNumber":507,"sourceCode":"      pagination_label: paginationLabel,\n      sidebar_label: sidebarLabel,\n    },\n  } = doc;\n  return {\n    title:\n      paginationLabel ?? sidebarLabel ?? options?.sidebarItemLabel ?? title,\n    permalink,\n  };\n}\n\nexport function toNavigationLink(\n  navigationItem: SidebarNavigationItem | undefined,\n  docsById: {[docId: string]: DocMetadataBase},\n): PropNavigationLink | undefined {\n  function getDocById(docId: string) {\n    const doc = docsById[docId];\n    if (!doc) {\n      throw new Error(\n        `Can't create navigation link: no doc found with id=${docId}`,\n      );\n    }\n    return doc;\n  }\n\n  if (!navigationItem) {\n    return undefined;\n  }\n\n  if (navigationItem.type === 'category') {\n    return navigationItem.link.type === 'doc'\n      ? toDocNavigationLink(getDocById(navigationItem.link.id))\n      : {\n          title: navigationItem.label,\n          permalink: navigationItem.link.permalink,\n        };\n  }","sourceCodeStart":489,"sourceCodeEnd":525,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts#L489-L525","documentation":"Thrown by getDocById() inside toNavigationLink(). When converting a SidebarNavigationItem (a doc or a doc-linked category) into a PropNavigationLink for theme rendering, the plugin looks the doc id up in docsById. If the id is absent the build aborts because navigation data would otherwise point at a non-existent page.","triggerScenarios":"A sidebar navigation item references a doc id that was filtered out (e.g. draft), renamed, or deleted between sidebar collection and navigation rendering; an inconsistency where sidebarNameToDocIds contains an id but docsById does not (plugin-internal state divergence); versioned navigation computed against the wrong version's docs.","commonSituations":"Race between draft filtering and navigation generation; manual mutation of sidebar structures via a custom generator returning ids not present in the docs array; bugs from custom plugins that inject nav items; partial cache (clear with `docusaurus clear`).","solutions":["Run `docusaurus clear` to wipe stale caches, then rebuild - the inconsistency is often caused by cached metadata.","If you use a custom SidebarItemsGenerator, ensure every returned doc id exists in the docs array passed to it.","Verify no doc referenced in sidebars has draft:true (drafts are excluded from docsById for navigation).","Check versioned sidebars align with versioned docs (no dangling ids)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// If you build navigation programmatically, guard against missing docs.\nfunction safeToNavigationLink(navItem, docsById) {\n  if (!navItem) return undefined;\n  if (navItem.type === 'category' && navItem.link?.type === 'doc') {\n    if (!docsById[navItem.link.id]) return undefined; // skip instead of throw\n  }\n  if (navItem.type === 'doc' && !docsById[navItem.id]) return undefined;\n  return navItem;\n}","typeGuard":"function navItemHasExistingDoc(navItem, docsById) {\n  if (navItem.type === 'doc') return Boolean(docsById[navItem.id]);\n  if (navItem.type === 'category' && navItem.link?.type === 'doc') {\n    return Boolean(docsById[navItem.link.id]);\n  }\n  return true;\n}","tryCatchPattern":null,"preventionTips":["Run `docusaurus clear` to drop stale caches before debugging navigation errors.","Ensure custom generators only return ids present in the docs array.","Avoid marking docs as draft if they are referenced as navigation links."],"tags":["docs","sidebar","navigation","internal"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}