{"record":{"id":"8beedca6fcde3d1d","repo":"mozilla/pdf.js","slug":"the-reference-does-not-point-to-a-page-dictionary","errorCode":null,"errorMessage":"The reference does not point to a /Page dictionary.","messagePattern":"The reference does not point to a /Page dictionary\\.","errorType":"exception","errorClass":"FormatError","httpStatus":null,"severity":"error","filePath":"src/core/catalog.js","lineNumber":1604,"sourceCode":"\n    // The page tree nodes have the count of all the leaves below them. To get\n    // how many pages are before we just have to walk up the tree and keep\n    // adding the count of siblings to the left of the node.\n    const xref = this.xref;\n    let total = 0,\n      ref = pageRef;\n    // Prevent circular references in the /Pages tree.\n    const visited = new RefSet();\n    visited.put(pageRef);\n\n    while (true) {\n      const node = await xref.fetchAsync(ref);\n      if (\n        isRefsEqual(ref, pageRef) &&\n        !isDict(node, \"Page\") &&\n        !(node instanceof Dict && !node.has(\"Type\") && node.has(\"Contents\"))\n      ) {\n        throw new FormatError(\n          \"The reference does not point to a /Page dictionary.\"\n        );\n      }\n      if (!node) {\n        break;\n      }\n      if (!(node instanceof Dict)) {\n        throw new FormatError(\"Node must be a dictionary.\");\n      }\n      const parentRef = node.getRaw(\"Parent\");\n      if (parentRef instanceof Ref) {\n        if (visited.has(parentRef)) {\n          throw new FormatError(\"Pages tree contains circular reference.\");\n        }\n        visited.put(parentRef);\n      }\n\n      const parent = await node.getAsync(\"Parent\");","sourceCodeStart":1586,"sourceCodeEnd":1622,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/catalog.js#L1586-L1622","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Validate the ref resolves to a /Page before calling getPageIndex by fetching and checking its /Type.","Repair the PDF if /Page nodes are missing /Type (qpdf/mutool).","Catch the FormatError and report the bad reference to the caller."],"exampleFix":"// before: passing an arbitrary ref of unknown kind\nconst idx = await pdfDoc.getPageIndex(someRef);\n\n// after: confirm the ref is a leaf Page first\nconst node = await pdfDoc.xref?.fetch?.(someRef); // internal; prefer getPage\n// simplest: obtain the ref from a loaded Page object, which is guaranteed /Page\nconst page = await pdfDoc.getPage(n);\nconst idx = await pdfDoc.getPageIndex(page.ref);","handlingStrategy":"type-guard","validationCode":"// Only call getPageIndex with a ref obtained from a loaded Page object,\n// which is guaranteed to be a /Page leaf.\nconst page = await pdf.getPage(n);\nconst ref = page.ref; // safe /Page reference\nconst idx = await pdf.getPageIndex(ref);","typeGuard":"// Narrow before calling: ensure the ref came from a Page proxy.\nfunction isPageRef(ref, page) {\n  return !!ref && typeof ref === 'object' && 'num' in ref && 'gen' in ref && page?.ref === ref;\n}","tryCatchPattern":"try {\n  const idx = await pdf.getPageIndex(ref);\n} catch (err) {\n  if (/does not point to a \\\\/Page dictionary/i.test(err?.message)) {\n    throw new TypeError('ref is not a /Page leaf reference', { cause: err });\n  }\n  throw err;\n}","preventionTips":["Obtain page refs from pdfDocument.getPage(n).ref, not from arbitrary tree traversal.","Never pass a /Pages (interior) or catalog reference to getPageIndex.","Repair PDFs whose /Page nodes lack /Type and /Contents (qpdf/mutool).","Catch and report bad refs rather than propagating the internal FormatError."],"tags":["pdf-structure","pages-tree","page-retrieval","validation","corrupt-pdf"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}