docusealco/docuseal · error · Pdfium::PdfiumError

Failed to get image matrix

Error message

Failed to get image matrix

What it means

Raised in redact_image_objects when FPDFPageObj_GetMatrix returns 0 for an image object that overlaps a redaction rect. The matrix is needed to map pixel-space redaction regions back onto the image, so a zero return stops pixel-level image redaction for that object. There is no check_last_error; the failure is rare and usually means a malformed image object or a pdfium build gap for that object variant.

Source

Thrown at lib/pdfium.rb:1434

      bounds_ptrs = Array.new(4) { FFI::MemoryPointer.new(:float) }
      matrix_ptr = FFI::MemoryPointer.new(:float, 6)

      Pdfium.FPDFPage_CountObjects(@page_ptr).times do |index|
        object_ptr = Pdfium.FPDFPage_GetObject(@page_ptr, index)

        next if object_ptr.null?
        next unless Pdfium.FPDFPageObj_GetType(object_ptr) == FPDF_PAGEOBJ_IMAGE
        next if Pdfium.FPDFPageObj_GetBounds(object_ptr, *bounds_ptrs).zero?

        obj_left, obj_bottom, obj_right, obj_top = bounds_ptrs.map(&:read_float)

        overlapping = rect_bounds.select do |left, bottom, right, top|
          obj_left < right && obj_right > left && obj_bottom < top && obj_top > bottom
        end

        next if overlapping.empty?

        raise PdfiumError, 'Failed to get image matrix' if Pdfium.FPDFPageObj_GetMatrix(object_ptr, matrix_ptr).zero?

        matrix = matrix_ptr.read_array_of_float(6)

        next if ((matrix[0] * matrix[3]) - (matrix[1] * matrix[2])).abs < 1e-9

        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)

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Rescue per image and skip it; text and rect redaction still apply
2. Fall back to covering the overlapping area with an opaque drawn rect
3. Pre-process the PDF through ghostscript to normalize image XObjects
4. Update libpdfium

Example fix

# before
page.redact(rects) { |bitmap, pixel_rects| blacken(bitmap, pixel_rects) }

# after - one bad image must not kill the page
begin
  page.redact(rects) { |bitmap, pixel_rects| blacken(bitmap, pixel_rects) }
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Failed to get image matrix'
  page.redact(rects) # retry without image processor: rects still cover the area
end

begin
  page.redact(rects) { |bitmap, pr| pixel_blacken(bitmap, pr) }
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Failed to get image matrix'
  page.redact(rects) # rect-cover fallback still hides the region
end

When it happens

Trigger: Calling redact with an image_processor block on pages containing images with missing or broken transformation matrices: inline images, unusual XObject dictionaries, generator-specific image objects.

Common situations: Image-redaction features on scanned or fax-derived PDFs and PDFs from niche producers.

Related errors

• Failed to unwrap form object
• Failed to remove page object
• Failed to get image bitmap
• Unsupported image bitmap format
• Failed to generate page content

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