mozilla/pdf.js · error · FormatError

Unhandled XObject subtype ${type.name}

Error message

Unhandled XObject subtype ${type.name}

What it means

FormatError thrown when an XObject's Subtype Name is a value other than Form, Image, or PS. PDF.js dispatches Image (buildImage), Form (buildFormXObject), and PS (ignored with an info log); any other subtype name is unsupported.

Source

Thrown at src/core/evaluator.js:1837

                  return;
                } else if (type.name === "Image") {
                  self
                    .buildPaintImageXObject({
                      resources,
                      image: xobj,
                      operatorList,
                      cacheKey: name,
                      localImageCache,
                      localColorSpaceCache,
                    })
                    .then(resolveXObject, rejectXObject);
                  return;
                } else if (type.name === "PS") {
                  // PostScript XObjects are unused when viewing documents.
                  // See section 4.7.1 of Adobe's PDF reference.
                  info("Ignored XObject subtype PS");
                } else {
                  throw new FormatError(
                    `Unhandled XObject subtype ${type.name}`
                  );
                }
                resolveXObject();
              }).catch(function (reason) {
                if (reason instanceof AbortException) {
                  return;
                }
                if (self.options.ignoreErrors) {
                  warn(`getOperatorList - ignoring XObject: "${reason}".`);
                  return;
                }
                throw reason;
              })
            );
            return;
          case OPS.setFont:
            const fontSize = args[1];

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true so the unsupported XObject is skipped.
2. Repair/convert the PDF to use standard /Form, /Image, or /PS subtypes.
3. Upgrade PDF.js in case support was added.

Example fix

// before
getDocument({ data }); // unsupported XObject subtype aborts

// after
getDocument({ data, ignoreErrors: true }); // unsupported subtype skipped

try {
  await page.render({ canvasContext, viewport }).promise;
} catch (e) {
  if (/Unhandled XObject subtype/.test(e.message)) {
    await reloadWith({ ignoreErrors: true });
  } else throw e;
}

When it happens

Trigger: An XObject stream carries a Subtype Name that is not /Form, /Image, or /PS (e.g. a custom or future/unknown subtype).

Common situations: Non-standard or experimental XObject subtypes, or PDFs from tools that emit vendor-specific subtypes.

Related errors

• getOperatorList - ignoring circular reference: ${objId}
• XObject must be referred to by name.
• XObject should be a stream
• XObject should have a Name subtype
• Unable to decode inline image: "${reason}".

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