mozilla/pdf.js · error · FormatError

Kid reference not found in parent's kids.

Error message

Kid reference not found in parent's kids.

What it means

Thrown by getPageIndex after scanning a parent's entire /Kids array without finding the current node's reference. The page tree is inconsistent: a node declares a /Parent that does not list it as a child, so the upward walk cannot determine the node's position.

Source

Thrown at src/core/catalog.js:1667

          xref.fetchAsync(kid).then(obj => {
            if (!(obj instanceof Dict)) {
              throw new FormatError("Kid node must be a dictionary.");
            }
            if (obj.has("Count")) {
              const count = obj.get("Count");
              if (Number.isInteger(count) && count >= 0) {
                total += count;
                return;
              }
              throw new FormatError("Count must be a (positive) integer.");
            }
            // Page leaf node.
            total++;
          })
        );
      }
      if (!found) {
        throw new FormatError("Kid reference not found in parent's kids.");
      }
      await Promise.all(kidPromises);
      ref = parentRef;
    }

    this.pageIndexCache.put(pageRef, total);
    return total;
  }

  get baseUrl() {
    const uri = this.#catDict.get("URI");
    if (uri instanceof Dict) {
      const base = uri.get("Base");
      if (typeof base === "string") {
        const absoluteUrl = createValidAbsoluteUrl(base, null, {
          tryConvertEncoding: true,
        });
        if (absoluteUrl) {

View on GitHub (pinned to 5903d58d58)

Solutions

1. Catch the error and fall back to a linear getPage scan to locate the index.
2. Repair the file with qpdf or Ghostscript to rebuild a consistent page tree.
3. Regenerate the PDF so every node's ref appears in its declared parent's /Kids.

Example fix

// before
const idx = await pdfDocument.getPageIndex(ref);

// after
let idx = -1;
try {
  idx = await pdfDocument.getPageIndex(ref);
} catch (e) {
  for (let i = 0; i < pdfDocument.numPages; i++) {
    const p = await pdfDocument.getPage(i);
    if (p.ref && p.ref.num === ref.num) { idx = i; break; }
  }
}

null

null

try {
  idx = await pdfDocument.getPageIndex(ref);
} catch (e) {
  for (let i = 0; i < pdfDocument.numPages; i++) {
    const p = await pdfDocument.getPage(i);
    if (p.ref && p.ref.num === ref.num) { idx = i; break; }
  }
}

When it happens

Trigger: A page or intermediate node has a /Parent pointing to a /Pages dictionary whose /Kids array does not contain this node's ref. The `found` flag stays false through the loop and triggers the throw.

Common situations: PDFs where /Parent was reassigned during editing/merging but /Kids not updated; nodes orphaned by partial tree edits; copy-paste of pages between documents without relinking; corrupt stitchers.

Related errors

• Parent must be a dictionary.
• Kids must be an array.
• Kid must be a reference.
• Kid node must be a dictionary.
• Count must be a (positive) integer.

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