{"record":{"id":"9ec237f7d942dd07","repo":"mozilla/pdf.js","slug":"xobject-must-be-referred-to-by-name","errorCode":null,"errorMessage":"XObject must be referred to by name.","messagePattern":"XObject must be referred to by name\\.","errorType":"exception","errorClass":"FormatError","httpStatus":null,"severity":"error","filePath":"src/core/evaluator.js","lineNumber":1775,"sourceCode":"        switch (fn | 0) {\n          case OPS.paintXObject:\n            // eagerly compile XForm objects\n            isValidName = args[0] instanceof Name;\n            name = args[0].name;\n\n            if (isValidName) {\n              const localImage = localImageCache.getByName(name);\n              if (localImage) {\n                addCachedImageOps(operatorList, localImage);\n                args = null;\n                continue;\n              }\n            }\n\n            next(\n              new Promise(function (resolveXObject, rejectXObject) {\n                if (!isValidName) {\n                  throw new FormatError(\"XObject must be referred to by name.\");\n                }\n\n                let xobj = xobjs.getRaw(name);\n                if (xobj instanceof Ref) {\n                  const cachedImage =\n                    localImageCache.getByRef(xobj) ||\n                    self._regionalImageCache.getByRef(xobj) ||\n                    self.globalImageCache.getData(xobj, self.pageIndex);\n                  if (cachedImage) {\n                    addCachedImageOps(operatorList, cachedImage);\n                    resolveXObject();\n                    return;\n                  }\n\n                  xobj = xref.fetch(xobj);\n                }\n\n                if (!(xobj instanceof BaseStream)) {","sourceCodeStart":1757,"sourceCodeEnd":1793,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/evaluator.js#L1757-L1793","documentation":"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.","triggerScenarios":"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.","commonSituations":"Corrupt content streams, incorrect hand-editing of PDF operators, or buggy generators emitting wrong operand types for Do.","solutions":["Enable ignoreErrors: true so the malformed Do is skipped with a warning.","Repair the content stream to use a proper /Name operand for Do.","Upgrade PDF.js."],"exampleFix":"// before\ngetDocument({ data }); // Do with non-Name aborts the page\n\n// after\ngetDocument({ data, ignoreErrors: true }); // malformed Do skipped","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await page.render({ canvasContext, viewport }).promise;\n} catch (e) {\n  if (/XObject must be referred to by name/.test(e.message)) {\n    await reloadWith({ ignoreErrors: true });\n  } else throw e;\n}","preventionTips":["Enable ignoreErrors for rendering of untrusted documents.","Sanitize PDFs before display.","Upgrade PDF.js regularly."],"tags":["pdf","xobject","malformed-pdf","rendering"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}