{"record":{"id":"01aab926eb0df034","repo":"mozilla/pdf.js","slug":"unknown-mask-format","errorCode":null,"errorMessage":"Unknown mask format.","messagePattern":"Unknown mask format\\.","errorType":"exception","errorClass":"FormatError","httpStatus":null,"severity":"error","filePath":"src/core/image.js","lineNumber":658,"sourceCode":"          for (let i = 0, ii = width * maxRows; i < ii; ++i) {\n            let opacity = 0;\n            const imageOffset = i * this.numComps;\n            for (let j = 0; j < this.numComps; ++j) {\n              const color = image[imageOffset + j];\n              const maskOffset = j * 2;\n              if (\n                color < this.mask[maskOffset] ||\n                color > this.mask[maskOffset + 1]\n              ) {\n                opacity = 255;\n                break;\n              }\n            }\n            buffer[i * stride + offset] = opacity;\n          }\n        };\n      } else {\n        throw new FormatError(\"Unknown mask format.\");\n      }\n    } else {\n      // No mask.\n      apply = (buffer, { maxRows, offset, stride }) => {\n        for (let i = 0, ii = width * maxRows; i < ii; ++i) {\n          buffer[i * stride + offset] = 255;\n        }\n      };\n    }\n\n    await apply(rgbaBuf, {\n      maxRows: actualHeight,\n      offset: 3,\n      stride: 4,\n    });\n  }\n\n  static #undoPreblend(buffer, length, matteR, matteG, matteB) {","sourceCodeStart":640,"sourceCodeEnd":676,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/image.js#L640-L676","documentation":"Thrown during alpha/mask application when this.mask is set but is neither a PDFImage instance (single mask) nor an Array (color-key mask). The code only knows how to apply those two mask representations; any other type indicates internal corruption of the mask field.","triggerScenarios":"A PDFImage has a /Mask that resolved to an unexpected type (e.g. a stream that failed to decode into a PDFImage, or a malformed color-key array). Reached while compositing image alpha during RGBA buffer fill.","commonSituations":"Internal invariant violation usually caused by upstream parsing of a malformed /Mask entry; rarely seen in normal use. Indicates the mask parsing path produced a value the apply step does not expect.","solutions":["Report the PDF to pdf.js maintainers with the file; this is typically an internal-state corruption, not a config issue.","Repair the PDF (qpdf --object-streams=generate) to normalize the /Mask entry.","Catch FormatError and skip compositing the mask, accepting a degraded alpha.","Regenerate the PDF ensuring /Mask is either an image XObject or a valid color-key range array."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Internal invariant; no public pre-check. If you parse PDFs manually, ensure\n// /Mask is either an image XObject Ref or an Array of number ranges.\nfunction maskShapeOk(mask) {\n  return mask == null || Array.isArray(mask) || typeof mask === 'object';\n}","typeGuard":"function isAcceptableMaskValue(mask) {\n  return mask == null || Array.isArray(mask) ||\n    (typeof mask === 'object' && mask !== null);\n}","tryCatchPattern":"try { await page.render({ canvasContext }).promise; }\ncatch (err) {\n  if (err?.message === 'Unknown mask format.') {\n    console.warn('Mask has unexpected type; skipping mask compositing.');\n  } else throw err;\n}","preventionTips":["Ensure /Mask is either a single image XObject or a color-key range Array when authoring PDFs.","Report internal-type corruption cases upstream with the PDF.","Catch FormatError and degrade alpha compositing per-page."],"tags":["pdf","image","mask","internal","malformed-pdf"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}