facebook/docusaurus · error · Error

Error when loading ${doc.id} in ${doc.sourceDirName}: the pa

Error message

Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.

What it means

Thrown by addDocNavigation when a doc's `pagination_prev` or `pagination_next` front matter points to an id that does not exist in the version's docs index. Only user-supplied ids can trigger this, because generated pagination always uses existing docs.

Source

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

  // Add sidebar/next/previous to the docs
  function addNavData(doc: DocMetadataBase): DocMetadata {
    const navigation = sidebarsUtils.getDocNavigation({
      docId: doc.id,
      displayedSidebar: doc.frontMatter.displayed_sidebar,
      unlistedIds,
    });

    const toNavigationLinkByDocId = (
      docId: string | null | undefined,
      type: 'prev' | 'next',
    ): PropNavigationLink | undefined => {
      if (!docId) {
        return undefined;
      }
      const navDoc = docsById[docId];
      if (!navDoc) {
        // This could only happen if user provided the ID through front matter
        throw new Error(
          `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
        );
      }
      // Gracefully handle explicitly providing an unlisted doc ID in production
      if (navDoc.unlisted) {
        return undefined;
      }
      return toDocNavigationLink(navDoc);
    };

    const previous =
      doc.frontMatter.pagination_prev !== undefined
        ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
        : toNavigationLink(navigation.previous, docsById);
    const next =
      doc.frontMatter.pagination_next !== undefined
        ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
        : toNavigationLink(navigation.next, docsById);

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Open the doc file and source dir printed in the message.
2. Update pagination_prev/pagination_next to a valid id, or remove the field.
3. Search the version's docs for the intended target id to confirm spelling.

Example fix

---
# before
pagination_next: instalation
---
---
# after
pagination_next: installation
---

const validIds = new Set(docs.map(d => d.id));
for (const ref of ['pagination_prev','pagination_next']) {
  const v = frontMatter[ref];
  if (v && !validIds.has(v)) throw new Error(`${ref}='${v}' is not a known doc id`);
}

const isValidDocRef = (id: string, docsById: Record<string, unknown>): id is string =>
  typeof id === 'string' && id in docsById;

When it happens

Trigger: Front matter sets pagination_prev/pagination_next to a doc id that was renamed, deleted, or never existed. docsById[docId] is undefined when resolving the navigation link.

Common situations: Renaming a doc id without updating pagination refs in neighbours, deleting a doc that others point to, or typos in the referenced id.

Related errors

• Doc with ID ${docId} wants to display sidebar ${sidebarName}
• Document id "${baseID}" cannot include slash.
• Can't create navigation link: no doc found with id=${docId}
• We couldn't compute a valid slug for document with ID "${bas
• Can't reference blog post authors by a key (such as '${key}'

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