mozilla/pdf.js · error · FormatError

The reference does not point to a /Page dictionary.

Error message

The reference does not point to a /Page dictionary.

What it means

Thrown in Catalog.getPageIndex() (catalog.js:1604) when the supplied pageRef, on its first fetch, does not resolve to a /Page-typed dictionary (and is not a dictionary lacking /Type but having /Contents, which is accepted as an implicit Page). getPageIndex walks up the Parent chain to compute a page's 0-based index, so the starting node must be a real Page.

Source

Thrown at src/core/catalog.js:1604

    // The page tree nodes have the count of all the leaves below them. To get
    // how many pages are before we just have to walk up the tree and keep
    // adding the count of siblings to the left of the node.
    const xref = this.xref;
    let total = 0,
      ref = pageRef;
    // Prevent circular references in the /Pages tree.
    const visited = new RefSet();
    visited.put(pageRef);

    while (true) {
      const node = await xref.fetchAsync(ref);
      if (
        isRefsEqual(ref, pageRef) &&
        !isDict(node, "Page") &&
        !(node instanceof Dict && !node.has("Type") && node.has("Contents"))
      ) {
        throw new FormatError(
          "The reference does not point to a /Page dictionary."
        );
      }
      if (!node) {
        break;
      }
      if (!(node instanceof Dict)) {
        throw new FormatError("Node must be a dictionary.");
      }
      const parentRef = node.getRaw("Parent");
      if (parentRef instanceof Ref) {
        if (visited.has(parentRef)) {
          throw new FormatError("Pages tree contains circular reference.");
        }
        visited.put(parentRef);
      }

      const parent = await node.getAsync("Parent");

View on GitHub (pinned to 5903d58d58)

Solutions

1. Ensure you pass a leaf /Page reference (e.g., one obtained from pdfDocument.getPage(n).then(p => p.ref) or pageRef) to getPageIndex, not an interior /Pages node.
2. Validate the ref resolves to a /Page before calling getPageIndex by fetching and checking its /Type.
3. Repair the PDF if /Page nodes are missing /Type (qpdf/mutool).
4. Catch the FormatError and report the bad reference to the caller.

Example fix

// before: passing an arbitrary ref of unknown kind
const idx = await pdfDoc.getPageIndex(someRef);

// after: confirm the ref is a leaf Page first
const node = await pdfDoc.xref?.fetch?.(someRef); // internal; prefer getPage
// simplest: obtain the ref from a loaded Page object, which is guaranteed /Page
const page = await pdfDoc.getPage(n);
const idx = await pdfDoc.getPageIndex(page.ref);

// Only call getPageIndex with a ref obtained from a loaded Page object,
// which is guaranteed to be a /Page leaf.
const page = await pdf.getPage(n);
const ref = page.ref; // safe /Page reference
const idx = await pdf.getPageIndex(ref);

// Narrow before calling: ensure the ref came from a Page proxy.
function isPageRef(ref, page) {
  return !!ref && typeof ref === 'object' && 'num' in ref && 'gen' in ref && page?.ref === ref;
}

try {
  const idx = await pdf.getPageIndex(ref);
} catch (err) {
  if (/does not point to a \\/Page dictionary/i.test(err?.message)) {
    throw new TypeError('ref is not a /Page leaf reference', { cause: err });
  }
  throw err;
}

When it happens

Trigger: pdfDocument.getPageIndex(ref) called with a Ref that points at a /Pages (intermediate) node or some other non-/Page dictionary. The very first iteration checks isRefsEqual(ref, pageRef) && !isDict(node,'Page') && !(implicit-page heuristic) and throws.

Common situations: Passing a catalog or /Pages-tree-interior reference to getPageIndex instead of a leaf /Page reference; a corrupt PDF where the Page node lacks both /Type=/Page and /Contents so the implicit-page heuristic fails; a ref obtained from an unreliable source.

Related errors

• Page count in top-level pages dictionary is not an integer.
• Pages tree contains circular reference.
• Page dictionary kid reference points to wrong type of object
• Page dictionary kids object is not an array.
• Page index ${pageIndex} not found.

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/8beedca6fcde3d1d. Report an issue: GitHub.