{"record":{"id":"ffe95deaf8bbe487","repo":"mozilla/pdf.js","slug":"image-exceeded-maximum-allowed-size-and-was-remove","errorCode":null,"errorMessage":"Image exceeded maximum allowed size and was removed.","messagePattern":"Image exceeded maximum allowed size and was removed\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/core/evaluator.js","lineNumber":630,"sourceCode":"    localColorSpaceCache,\n  }) {\n    const { maxImageSize, ignoreErrors, isOffscreenCanvasSupported } =\n      this.options;\n\n    const { dict } = image;\n    const imageRef = dict.objId;\n    const w = dict.get(\"W\", \"Width\");\n    const h = dict.get(\"H\", \"Height\");\n\n    if (!(w && typeof w === \"number\") || !(h && typeof h === \"number\")) {\n      warn(\"Image dimensions are missing, or not numbers.\");\n      return;\n    }\n    if (maxImageSize !== -1 && w * h > maxImageSize) {\n      const msg = \"Image exceeded maximum allowed size and was removed.\";\n\n      if (!ignoreErrors) {\n        throw new Error(msg);\n      }\n      warn(msg);\n      return;\n    }\n\n    let optionalContent;\n    if (dict.has(\"OC\")) {\n      optionalContent = await this.parseMarkedContentProps(\n        dict.get(\"OC\"),\n        resources\n      );\n    }\n\n    const imageMask = dict.get(\"IM\", \"ImageMask\") || false;\n    let imgData, fn, args;\n    if (imageMask) {\n      // This depends on a tmpCanvas being filled with the\n      // current fillStyle, such that processing the pixel","sourceCodeStart":612,"sourceCodeEnd":648,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/evaluator.js#L612-L648","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Increase maxImageSize (e.g. 10x) or set it to -1 to disable the guard entirely.","Pass getDocument({ ...getDocumentParams, ignoreErrors: true }) so oversized images are skipped with a warning instead of aborting the page render.","Pre-process the source PDF to downscale or recompress oversized images before feeding it to PDF.js.","If you need the limit, render at a lower viewport scale so the on-screen cost stays bounded while keeping maxImageSize generous."],"exampleFix":"// before\ngetDocument({ data, maxImageSize: 1_000_000 }); // trips on a 1024x1024 image\n\n// after\ngetDocument({ data, maxImageSize: -1 }); // unlimited (default)\n// or, keep a guard but tolerate overruns:\ngetDocument({ data, maxImageSize: 1_000_000, ignoreErrors: true });","handlingStrategy":"validation","validationCode":"// Verify the option before rendering. maxImageSize <= 0 means unlimited.\nconst params = { data, maxImageSize: 1_000_000 };\nif (typeof params.maxImageSize === 'number' && params.maxImageSize > 0) {\n  console.warn(\n    `maxImageSize=${params.maxImageSize} will throw on images larger than that pixel count.`\n  );\n}\n// To disable the guard entirely:\n// params.maxImageSize = -1;\nconst task = pdfjsLib.getDocument(params);","typeGuard":null,"tryCatchPattern":"// Wrap page render so an oversized image fails the page, not the app.\ntry {\n  await page.render({ canvasContext, viewport }).promise;\n} catch (e) {\n  if (/Image exceeded maximum allowed size/.test(e.message)) {\n    // Re-render with maxImageSize disabled or ignoreErrors enabled.\n  } else throw e;\n}","preventionTips":["Leave maxImageSize at -1 unless you have a concrete memory budget.","When capping, prefer ignoreErrors:true so overruns degrade instead of aborting.","Document the chosen maxImageSize in your deployment config so it is not mistaken for a bug."],"tags":["pdf","image","configuration","memory","rendering"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}