docusealco/docuseal · error · Pdfium::PdfiumError

Failed to create new document

Error message

Failed to create new document

What it means

Raised by Pdfium::Document.create when the native FPDF_CreateNewDocument returns a NULL handle. Pdfium.check_last_error runs first and raises a richer message (with the PDFium error code) whenever one is recorded, so this exact plain message means PDFium returned NULL without recording an error. In practice this is an allocation failure inside the native library, since creating an empty document has almost no other failure modes.

Source

Thrown at lib/pdfium.rb:586

      result = Pdfium.FPDF_ImportPages(@document_ptr, src_doc.document_ptr, pages, index || page_count)

      raise PdfiumError, 'Failed to import pages' if result.zero?

      Pdfium.FPDF_ImportAcroForm(@document_ptr, src_doc.document_ptr)

      @page_count = nil

      result
    end

    def self.create
      doc_ptr = Pdfium.FPDF_CreateNewDocument()

      if doc_ptr.null?
        Pdfium.check_last_error('Failed to create new document')

        raise PdfiumError, 'Failed to create new document'
      end

      doc = new(doc_ptr)

      return doc unless block_given?

      begin
        yield doc
      ensure
        doc.close
      end
    end

    def self.open_file(file_path, password = nil)
      doc_ptr = Pdfium.FPDF_LoadDocument(file_path, password)

      if doc_ptr.null?
        Pdfium.check_last_error("Failed to load document from file '#{file_path}'")

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Check process memory and close/release open Pdfium::Document objects (they hold native memory until close) before retrying
2. Raise the container/cgroup memory limit or move PDF work to a dedicated worker process
3. Retry Document.create once after GC.start to absorb transient allocation pressure
4. Verify the libpdfium shared library loads and matches your platform (see the LoadError guard at the top of lib/pdfium.rb)

Example fix

# before
doc = Pdfium::Document.create
doc.get_page(0)

# after - block form guarantees close; retry absorbs transient allocation failure
begin
  retries ||= 0
  Pdfium::Document.create do |doc|
    doc.get_page(0)
  end
rescue Pdfium::PdfiumError
  GC.start
  (retries += 1) <= 1 ? retry : raise
end

begin
  retries ||= 0
  Pdfium::Document.create { |doc| work(doc) }
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Failed to create new document'
  GC.start
  (retries += 1) <= 1 ? retry : raise
end

When it happens

Trigger: Calling Pdfium::Document.create when the process has exhausted memory or address space: many large documents open at once, huge bitmaps rendered previously, strict container/cgroup memory caps, or a broken/mismatched libpdfium build.

Common situations: Long-running Rails background jobs that keep Document/Page objects alive; Docker containers with low memory limits; 32-bit processes; pdfium binaries that fail to allocate their internal document pool.

Related errors

• 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.
• Failed to save document
• Failed to load page #{page_index}, pointer is NULL.

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