facebook/docusaurus · error · Error

no version doc found by id=${id}

Error message

no version doc found by id=${id}

What it means

Thrown by useDocById() when the current docs version's docs map has no entry for the given id. The hook first calls useDocsVersion() to get the active version, then indexes version.docs[id]; a miss throws. An undefined id returns undefined early (null-safe overload), so this throw specifically means a non-empty id that doesn't match any doc in the current version.

Source

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

  PropSidebarBreadcrumbsItem,
} from '@docusaurus/plugin-content-docs';

/**
 * A null-safe way to access a doc's data by ID in the active version.
 */
export function useDocById(id: string): PropVersionDoc;
/**
 * A null-safe way to access a doc's data by ID in the active version.
 */
export function useDocById(id: string | undefined): PropVersionDoc | undefined;
export function useDocById(id: string | undefined): PropVersionDoc | undefined {
  const version = useDocsVersion();
  if (!id) {
    return undefined;
  }
  const doc = version.docs[id];
  if (!doc) {
    throw new Error(`no version doc found by id=${id}`);
  }
  return doc;
}

/**
 * Pure function, similar to `Array#find`, but works on the sidebar tree.
 */
export function findSidebarCategory(
  sidebar: PropSidebar,
  predicate: (category: PropSidebarItemCategory) => boolean,
): PropSidebarItemCategory | undefined {
  for (const item of sidebar) {
    if (item.type === 'category') {
      if (predicate(item)) {
        return item;
      }
      const subItem = findSidebarCategory(item.items, predicate);
      if (subItem) {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Verify the id exists in the current version: search version docs for that exact id string (case/slash-sensitive).
2. Fix stale references in sidebars config / navbar / doc cards to the renamed or correct id.
3. If the doc was moved to another version, use a version-aware lookup (useLayoutDoc) or a permalink instead.
4. If id may legitimately be absent, use the null-safe overload: pass `undefined` to short-circuit, or pre-check before calling.

Example fix

// before
const doc = useDocById('tutorial/basics'); // typo, real id is 'tutorial/intro'
// after
const doc = useDocById('tutorial/intro');

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

function useDocByIdSafe(id: string | undefined) {
  const version = useDocsVersion();
  if (!id || !(id in version.docs)) return undefined;
  return version.docs[id];
}
// use useDocByIdSafe() instead of useDocById() when absence is acceptable

const isKnownDocId = (
  id: string,
  docs: Record<string, unknown>,
): id is keyof typeof docs => id in docs;

When it happens

Trigger: Passing a doc id from a sidebar config or cross-reference that doesn't exist in the active version (typo, renamed doc, or doc only present in another version); referencing a doc id after a doc was deleted or its id changed.

Common situations: Renaming a doc's slug/id but leaving stale `docId` references in sidebars.json or navbar items; versioned setups where the id exists in version X but the active version is Y; cross-version links pointing at ids not present in the current version.

Related errors

• Hook is called outside the <DocsPreferredVersionContextProvi
• Couldn't find any doc with id "${docId}" in version${version
• Hook is called outside the <DocsVersionProvider>.
• ${pluginIdLogPrefix}: this version already exists! Use a ver
• ${pluginIdLogPrefix}: no docs found in path=${docsDir}.

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