mozilla/pdf.js · error · FormatError

XObject should have a Name subtype

Error message

XObject should have a Name subtype

What it means

FormatError thrown when a valid XObject stream's dict has a 'Subtype' entry that is not a PDF Name. The subtype (Form/Image/PS) must be a Name to be dispatched; any other type is malformed.

Source

Thrown at src/core/evaluator.js:1799

                    localImageCache.getByRef(xobj) ||
                    self._regionalImageCache.getByRef(xobj) ||
                    self.globalImageCache.getData(xobj, self.pageIndex);
                  if (cachedImage) {
                    addCachedImageOps(operatorList, cachedImage);
                    resolveXObject();
                    return;
                  }

                  xobj = xref.fetch(xobj);
                }

                if (!(xobj instanceof BaseStream)) {
                  throw new FormatError("XObject should be a stream");
                }

                const type = xobj.dict.get("Subtype");
                if (!(type instanceof Name)) {
                  throw new FormatError("XObject should have a Name subtype");
                }

                if (type.name === "Form") {
                  stateManager.save();
                  self
                    .buildFormXObject(
                      resources,
                      xobj,
                      null,
                      operatorList,
                      task,
                      stateManager.state.clone({ newPath: true }),
                      localColorSpaceCache,
                      seenRefs
                    )
                    .then(function () {
                      stateManager.restore();
                      resolveXObject();

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true to skip the XObject.
2. Repair the XObject stream to include a valid /Subtype Name (Form, Image, or PS).
3. Upgrade PDF.js.

Example fix

// before
getDocument({ data }); // XObject without Name Subtype aborts

// after
getDocument({ data, ignoreErrors: true }); // bad XObject skipped

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

When it happens

Trigger: An XObject stream whose /Subtype is missing, a string, a number, or an unresolvable reference, so 'type instanceof Name' is false.

Common situations: Corrupt XObject dictionaries, missing Subtype entries, or broken indirect refs to the Subtype value.

Related errors

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

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