docusealco/docuseal · error · Pdfium::PdfiumError

Failed to load signature #{index}, pointer is NULL.

Error message

Failed to load signature #{index}, pointer is NULL.

What it means

Raised by Pdfium::Signature.new when FPDF_GetSignatureObject returns NULL for the given index. There is no check_last_error on this path; the near-universal cause is an index at or above the document's signature count (FPDF_GetSignatureCount). Document#signatures only constructs Signature objects for 0...signature_count, so hitting this directly means manual construction with an unchecked index or a count/index mismatch.

Source

Thrown at lib/pdfium.rb:858

      Pdfium.FPDF_CloseDocument(@document_ptr) unless @document_ptr.null?

      @document_ptr = FFI::Pointer::NULL
      @source_buffer = nil

      @closed = true
    end
  end

  class Signature
    attr_reader :document, :index, :signature_ptr

    def initialize(document, index)
      @document = document
      @index = index
      @signature_ptr = Pdfium.FPDF_GetSignatureObject(document.document_ptr, index)

      raise PdfiumError, "Failed to load signature #{index}, pointer is NULL." if @signature_ptr.null?
    end

    def byte_range
      @byte_range ||=
        begin
          count = Pdfium.FPDFSignatureObj_GetByteRange(signature_ptr, nil, 0)
          buffer = FFI::MemoryPointer.new(:int, count)
          Pdfium.FPDFSignatureObj_GetByteRange(signature_ptr, buffer, count)

          buffer.read_array_of_int(count)
        end
    end

    def signed_end
      @signed_end ||= byte_range.last(2).sum
    end

    def contents

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Use doc.signatures instead of constructing Signature manually
2. Validate index against doc.signature_count before constructing
3. Re-fetch signature_count after document mutations instead of trusting a cached value

Example fix

# before
(0..doc.signature_count).each { |i| use Pdfium::Signature.new(doc, i) } # off-by-one

# after
doc.signatures.each { |sig| use sig }

raise ArgumentError, 'no such signature' unless index >= 0 && index < doc.signature_count
sig = Pdfium::Signature.new(doc, index)

begin
  Pdfium::Signature.new(doc, index)
rescue Pdfium::PdfiumError => e
  raise unless e.message.include?('Failed to load signature')
  nil # caller treats as absent signature
end

When it happens

Trigger: Pdfium::Signature.new(doc, 3) on a document with 2 signatures; iterating 0..doc.signature_count inclusively instead of 0...count; counting signatures on one document but constructing Signature objects against another.

Common situations: Hand-written signature-verification flows (verify_pdf_signature.rb style) with inclusive range mistakes; caching a count then mutating the document before use.

Related errors

• Page index #{page_index} out of range (0..#{page_count - 1})
• Failed to create new document
• Failed to load document from file '#{file_path}', pointer is
• Failed to load document from memory, pointer is NULL.
• Failed to load document from IO, pointer is NULL.

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