mozilla/pdf.js · warning · FormatError

PageLabel is not a dictionary.

Error message

PageLabel is not a dictionary.

What it means

Thrown in Catalog.#readPageLabels() (catalog.js:869) when an entry retrieved from the PageLabels NumberTree (numbered by page index) is not a Dict. Each PageLabel entry should be a dictionary describing the label style/prefix/start for a page range. Note: the pageLabels getter wraps #readPageLabels in try/catch and downgrades this FormatError to a 'Unable to read page labels.' warning, returning null labels — so the user-visible effect is loss of page labels, not a load failure.

Source

Thrown at src/core/catalog.js:869

  #readPageLabels() {
    const nums = this.rawPageLabels;
    if (!nums) {
      return null;
    }

    const pageLabels = new Array(this.numPages);
    let style = null,
      prefix = "";

    let currentLabel = "",
      currentIndex = 1;

    for (let i = 0, ii = this.numPages; i < ii; i++) {
      const labelDict = nums.get(i);

      if (labelDict !== undefined) {
        if (!(labelDict instanceof Dict)) {
          throw new FormatError("PageLabel is not a dictionary.");
        }

        if (
          labelDict.has("Type") &&
          !isName(labelDict.get("Type"), "PageLabel")
        ) {
          throw new FormatError("Invalid type in PageLabel dictionary.");
        }

        if (labelDict.has("S")) {
          const s = labelDict.get("S");
          if (!(s instanceof Name)) {
            throw new FormatError("Invalid style in PageLabel dictionary.");
          }
          style = s.name;
        } else {
          style = null;
        }

View on GitHub (pinned to 5903d58d58)

Solutions

  1. This error is already caught and degraded to a warning by the pageLabels getter — no labels will display, but the document loads. Confirm labels are non-essential for your use case.
  2. Repair the PDF with qpdf/mutool to rebuild a clean PageLabels tree if labels matter.
  3. If generating PDFs, ensure each PageLabels leaf is a proper dictionary with /S, /P, /St keys.
  4. Treat pdfDocument.pageLabels === null as 'labels unavailable' rather than an error in your UI.
Defensive patterns

Strategy: fallback

Validate before calling

// Labels are optional metadata; you cannot cheaply pre-validate the number tree.
// Design UI so null pageLabels is a normal 'no labels' state.

Try / catch

// PDF.js already catches this in the pageLabels getter and warns.
// Treat null as 'labels unavailable':
const labels = pdf.pageLabels; // may be null after a console warning
if (!labels) {
  // fall back to plain 1..numPages numbering
}

Prevention

When it happens

Trigger: nums.get(i) returns a defined value that is not a Dict (e.g., a string, name, or array stored in the PageLabels number tree). Reached when pdfDocument.pageLabels is read or when the viewer requests page labels for the sidebar.

Common situations: A PDF producer that wrote a malformed PageLabels tree; a corrupt number-tree leaf; an edited PDF with hand-added bad entries. Low frequency; usually only affects label display.

Related errors

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