mozilla/pdf.js · error · FormatError

XObject must be referred to by name.

Error message

XObject must be referred to by name.

What it means

FormatError thrown while handling the 'Do' (invoke XObject) operator when its operand is not a PDF Name object. The PDF spec requires Do to take a name that keys into the XObject resource dictionary; a non-Name operand is malformed.

Source

Thrown at src/core/evaluator.js:1775

        switch (fn | 0) {
          case OPS.paintXObject:
            // eagerly compile XForm objects
            isValidName = args[0] instanceof Name;
            name = args[0].name;

            if (isValidName) {
              const localImage = localImageCache.getByName(name);
              if (localImage) {
                addCachedImageOps(operatorList, localImage);
                args = null;
                continue;
              }
            }

            next(
              new Promise(function (resolveXObject, rejectXObject) {
                if (!isValidName) {
                  throw new FormatError("XObject must be referred to by name.");
                }

                let xobj = xobjs.getRaw(name);
                if (xobj instanceof Ref) {
                  const cachedImage =
                    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)) {

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true so the malformed Do is skipped with a warning.
2. Repair the content stream to use a proper /Name operand for Do.
3. Upgrade PDF.js.

Example fix

// before
getDocument({ data }); // Do with non-Name aborts the page

// after
getDocument({ data, ignoreErrors: true }); // malformed Do skipped

try {
  await page.render({ canvasContext, viewport }).promise;
} catch (e) {
  if (/XObject must be referred to by name/.test(e.message)) {
    await reloadWith({ ignoreErrors: true });
  } else throw e;
}

When it happens

Trigger: A content stream emits a Do operator whose argument is a number/string/null instead of a Name; isValidName is false and the inner promise throws before any resource lookup. The .catch at the XObject handler honors ignoreErrors.

Common situations: Corrupt content streams, incorrect hand-editing of PDF operators, or buggy generators emitting wrong operand types for Do.

Related errors

• getOperatorList - ignoring circular reference: ${objId}
• XObject should be a stream
• XObject should have a Name subtype
• 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/9ec237f7d942dd07. Report an issue: GitHub.