mozilla/pdf.js · error · FormatError

Unknown mask format.

Error message

Unknown mask format.

What it means

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.

Source

Thrown at src/core/image.js:658

          for (let i = 0, ii = width * maxRows; i < ii; ++i) {
            let opacity = 0;
            const imageOffset = i * this.numComps;
            for (let j = 0; j < this.numComps; ++j) {
              const color = image[imageOffset + j];
              const maskOffset = j * 2;
              if (
                color < this.mask[maskOffset] ||
                color > this.mask[maskOffset + 1]
              ) {
                opacity = 255;
                break;
              }
            }
            buffer[i * stride + offset] = opacity;
          }
        };
      } else {
        throw new FormatError("Unknown mask format.");
      }
    } else {
      // No mask.
      apply = (buffer, { maxRows, offset, stride }) => {
        for (let i = 0, ii = width * maxRows; i < ii; ++i) {
          buffer[i * stride + offset] = 255;
        }
      };
    }

    await apply(rgbaBuf, {
      maxRows: actualHeight,
      offset: 3,
      stride: 4,
    });
  }

  static #undoPreblend(buffer, length, matteR, matteG, matteB) {

View on GitHub (pinned to 5903d58d58)

Solutions

1. Report the PDF to pdf.js maintainers with the file; this is typically an internal-state corruption, not a config issue.
2. Repair the PDF (qpdf --object-streams=generate) to normalize the /Mask entry.
3. Catch FormatError and skip compositing the mask, accepting a degraded alpha.
4. Regenerate the PDF ensuring /Mask is either an image XObject or a valid color-key range array.

// Internal invariant; no public pre-check. If you parse PDFs manually, ensure
// /Mask is either an image XObject Ref or an Array of number ranges.
function maskShapeOk(mask) {
  return mask == null || Array.isArray(mask) || typeof mask === 'object';
}

function isAcceptableMaskValue(mask) {
  return mask == null || Array.isArray(mask) ||
    (typeof mask === 'object' && mask !== null);
}

try { await page.render({ canvasContext }).promise; }
catch (err) {
  if (err?.message === 'Unknown mask format.') {
    console.warn('Mask has unexpected type; skipping mask compositing.');
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Reading gray scale from a color image: ${numComps}
• Unable to decode inline image: "${reason}".
• Invalid image width: ${width} or height: ${height}
• Bits per component missing in image: ${this.imageMask}
• Images with ${image.numComps} color components not supported

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