{"record":{"id":"1fac0e118aabaaf2","repo":"docusealco/docuseal","slug":"failed-to-create-new-document","errorCode":null,"errorMessage":"Failed to create new document","messagePattern":"Failed to create new document","errorType":"exception","errorClass":"Pdfium::PdfiumError","httpStatus":null,"severity":"error","filePath":"lib/pdfium.rb","lineNumber":586,"sourceCode":"\n      result = Pdfium.FPDF_ImportPages(@document_ptr, src_doc.document_ptr, pages, index || page_count)\n\n      raise PdfiumError, 'Failed to import pages' if result.zero?\n\n      Pdfium.FPDF_ImportAcroForm(@document_ptr, src_doc.document_ptr)\n\n      @page_count = nil\n\n      result\n    end\n\n    def self.create\n      doc_ptr = Pdfium.FPDF_CreateNewDocument()\n\n      if doc_ptr.null?\n        Pdfium.check_last_error('Failed to create new document')\n\n        raise PdfiumError, 'Failed to create new document'\n      end\n\n      doc = new(doc_ptr)\n\n      return doc unless block_given?\n\n      begin\n        yield doc\n      ensure\n        doc.close\n      end\n    end\n\n    def self.open_file(file_path, password = nil)\n      doc_ptr = Pdfium.FPDF_LoadDocument(file_path, password)\n\n      if doc_ptr.null?\n        Pdfium.check_last_error(\"Failed to load document from file '#{file_path}'\")","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/lib/pdfium.rb#L568-L604","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check process memory and close/release open Pdfium::Document objects (they hold native memory until close) before retrying","Raise the container/cgroup memory limit or move PDF work to a dedicated worker process","Retry Document.create once after GC.start to absorb transient allocation pressure","Verify the libpdfium shared library loads and matches your platform (see the LoadError guard at the top of lib/pdfium.rb)"],"exampleFix":"# before\ndoc = Pdfium::Document.create\ndoc.get_page(0)\n\n# after - block form guarantees close; retry absorbs transient allocation failure\nbegin\n  retries ||= 0\n  Pdfium::Document.create do |doc|\n    doc.get_page(0)\n  end\nrescue Pdfium::PdfiumError\n  GC.start\n  (retries += 1) <= 1 ? retry : raise\nend","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"begin\n  retries ||= 0\n  Pdfium::Document.create { |doc| work(doc) }\nrescue Pdfium::PdfiumError => e\n  raise unless e.message == 'Failed to create new document'\n  GC.start\n  (retries += 1) <= 1 ? retry : raise\nend","preventionTips":["Always use the block form of Document.create so the native handle is freed deterministically","Close documents before starting memory-heavy work; pdfium native memory is invisible to the Ruby GC","Set a memory limit/monitor on workers doing PDF processing so allocation failures surface early"],"tags":["pdfium","ffi","out-of-memory","document-creation","ruby"],"backgroundTag":"memory-allocation-failure","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}