mozilla/pdf.js · error · FormatError

XObject should be a stream

Error message

XObject should be a stream

What it means

FormatError thrown when a named XObject resource, after being fetched from the xref (if it was an indirect Ref), is not a BaseStream. PDF XObjects must be streams; a non-stream entry is corrupt or the wrong object type.

Source

Thrown at src/core/evaluator.js:1794

                }

                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)) {
                  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,

View on GitHub (pinned to 5903d58d58)

Solutions

1. Enable ignoreErrors: true to skip the bad XObject.
2. Repair the PDF so the XObject entry is a valid stream.
3. Upgrade PDF.js.

Example fix

// before
getDocument({ data }); // non-stream XObject aborts render

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

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

When it happens

Trigger: The XObject resource dictionary resolves the name to something that is not a stream (a dict, number, null, or broken indirect reference), so the 'instanceof BaseStream' check fails.

Common situations: Truncated PDFs where the stream object is missing/corrupt, indirect references that resolve to the wrong object, or generators that place a dictionary where a stream XObject is required.

Related errors

• getOperatorList - ignoring circular reference: ${objId}
• XObject must be referred to by name.
• 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/51b49fcadd0079be. Report an issue: GitHub.