docusealco/docuseal · warning · Pdfium::PdfiumError

Unsupported image bitmap format

Error message

Unsupported image bitmap format

What it means

Raised by extract_image_bitmap when the bitmap's reported format is outside BITMAP_FORMAT_BANDS, which maps only the FPDFBitmap codes 1-4 (gray, bgr, bgrx, bgra). FPDFBitmap_Unknown (0) and any other code yield a nil format and trigger this raise. In practice pdfium reports unknown for images it could not decode into a standard pixel layout, such as 1-bit stencil/image masks.

Source

Thrown at lib/pdfium.rb:1458

        bitmap = extract_image_bitmap(object_ptr)
        pixel_rects = image_pixel_rects(matrix, bitmap[:width], bitmap[:height], overlapping)

        next if pixel_rects.empty?

        jpeg = yield(bitmap, pixel_rects)

        load_image_jpeg(object_ptr, jpeg) if jpeg
      end
    end

    def extract_image_bitmap(object_ptr)
      bitmap_ptr = Pdfium.FPDFImageObj_GetBitmap(object_ptr)

      raise PdfiumError, 'Failed to get image bitmap' if bitmap_ptr.nil? || bitmap_ptr.null?

      format, bands = BITMAP_FORMAT_BANDS[Pdfium.FPDFBitmap_GetFormat(bitmap_ptr)]

      raise PdfiumError, 'Unsupported image bitmap format' if format.nil?

      image_width = Pdfium.FPDFBitmap_GetWidth(bitmap_ptr)
      image_height = Pdfium.FPDFBitmap_GetHeight(bitmap_ptr)
      stride = Pdfium.FPDFBitmap_GetStride(bitmap_ptr)

      data = Pdfium.FPDFBitmap_GetBuffer(bitmap_ptr).read_bytes(stride * image_height)

      row_size = image_width * bands

      data = Array.new(image_height) { |row| data.byteslice(row * stride, row_size) }.join if stride != row_size

      { data:, width: image_width, height: image_height, bands:, format: }
    ensure
      Pdfium.FPDFBitmap_Destroy(bitmap_ptr) if bitmap_ptr && !bitmap_ptr.null?
    end

    def image_pixel_rects(matrix, image_width, image_height, rect_bounds)
      a, b, c, d, e, f = matrix

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Rescue per image and fall back to covering the overlap with an opaque drawn rect
2. Rasterize or normalize the PDF (ghostscript) before redaction
3. Update libpdfium
4. Treat unknown-format images as not pixel-redactable and log them for review

Example fix

# before
page.redact(rects) { |bitmap, pr| pixel_blacken(bitmap, pr) }

# after
begin
  page.redact(rects) { |bitmap, pr| pixel_blacken(bitmap, pr) }
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Unsupported image bitmap format'
  page.redact(rects) # draw-only fallback for this page's images
end

begin
  page.redact(rects) { |bitmap, pr| pixel_blacken(bitmap, pr) }
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Unsupported image bitmap format'
  page.redact(rects) # cover-rect fallback for stencil-mask images
end

When it happens

Trigger: Same redaction pipeline as error 38, but the bitmap exists while its pixel format is unknown: monochrome image masks, stencil masks used for signatures/stamps, partially decoded streams.

Common situations: Scanned documents with monochrome image masks; signature and stamp overlays stored as stencil masks.

Related errors

• Failed to get image matrix
• Failed to get image bitmap
• Failed to generate page content
• Failed to load text page
• Failed to unwrap form object

AI-assisted analysis of docusealco/docuseal@004a22c1c8 (2026-08-21). Data as JSON: /api/errors/a969d6d94aa5848d. Report an issue: GitHub.