mozilla/pdf.js · error · Error

Image exceeded maximum allowed size and was removed.

Error message

Image exceeded maximum allowed size and was removed.

What it means

Thrown by buildPaintImageXObject when an image's pixel count (Width x Height) exceeds the configured 'maxImageSize' option. PDF.js uses this as a memory-safety guard. It is only active when 'maxImageSize' is set to a positive value; the default is -1 (unlimited), so with default options this error can never fire.

Source

Thrown at src/core/evaluator.js:630

    localColorSpaceCache,
  }) {
    const { maxImageSize, ignoreErrors, isOffscreenCanvasSupported } =
      this.options;

    const { dict } = image;
    const imageRef = dict.objId;
    const w = dict.get("W", "Width");
    const h = dict.get("H", "Height");

    if (!(w && typeof w === "number") || !(h && typeof h === "number")) {
      warn("Image dimensions are missing, or not numbers.");
      return;
    }
    if (maxImageSize !== -1 && w * h > maxImageSize) {
      const msg = "Image exceeded maximum allowed size and was removed.";

      if (!ignoreErrors) {
        throw new Error(msg);
      }
      warn(msg);
      return;
    }

    let optionalContent;
    if (dict.has("OC")) {
      optionalContent = await this.parseMarkedContentProps(
        dict.get("OC"),
        resources
      );
    }

    const imageMask = dict.get("IM", "ImageMask") || false;
    let imgData, fn, args;
    if (imageMask) {
      // This depends on a tmpCanvas being filled with the
      // current fillStyle, such that processing the pixel

View on GitHub (pinned to 5903d58d58)

Solutions

1. Increase maxImageSize (e.g. 10x) or set it to -1 to disable the guard entirely.
2. Pass getDocument({ ...getDocumentParams, ignoreErrors: true }) so oversized images are skipped with a warning instead of aborting the page render.
3. Pre-process the source PDF to downscale or recompress oversized images before feeding it to PDF.js.
4. If you need the limit, render at a lower viewport scale so the on-screen cost stays bounded while keeping maxImageSize generous.

Example fix

// before
getDocument({ data, maxImageSize: 1_000_000 }); // trips on a 1024x1024 image

// after
getDocument({ data, maxImageSize: -1 }); // unlimited (default)
// or, keep a guard but tolerate overruns:
getDocument({ data, maxImageSize: 1_000_000, ignoreErrors: true });

// Verify the option before rendering. maxImageSize <= 0 means unlimited.
const params = { data, maxImageSize: 1_000_000 };
if (typeof params.maxImageSize === 'number' && params.maxImageSize > 0) {
  console.warn(
    `maxImageSize=${params.maxImageSize} will throw on images larger than that pixel count.`
  );
}
// To disable the guard entirely:
// params.maxImageSize = -1;
const task = pdfjsLib.getDocument(params);

// Wrap page render so an oversized image fails the page, not the app.
try {
  await page.render({ canvasContext, viewport }).promise;
} catch (e) {
  if (/Image exceeded maximum allowed size/.test(e.message)) {
    // Re-render with maxImageSize disabled or ignoreErrors enabled.
  } else throw e;
}

When it happens

Trigger: Calling getDocument({ maxImageSize: N }) (or rendering a page derived from it) where the page contains an image whose W*H > N, and ignoreErrors is false (the default).

Common situations: Apps on memory-constrained platforms (mobile, embedded, serverless) set maxImageSize to cap peak memory; large scanned or image-heavy PDFs then trip it. Mis-typing the value (e.g. 1e6 when 1e8 was intended) also triggers it on otherwise normal images.

Related errors

• Unable to decode inline image: "${reason}".
• mapCidRange - ignoring data above MAX_MAP_RANGE.
• mapBfRange - ignoring data above MAX_MAP_RANGE.
• mapBfRangeToArray - ignoring data above MAX_MAP_RANGE.
• Unknown CMap name: ${name}

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