{"record":{"id":"e5aceb66be84132b","repo":"docusealco/docuseal","slug":"failed-to-import-pages","errorCode":null,"errorMessage":"Failed to import pages","messagePattern":"Failed to import pages","errorType":"exception","errorClass":"Pdfium::PdfiumError","httpStatus":null,"severity":"error","filePath":"lib/pdfium.rb","lineNumber":571,"sourceCode":"\n    def page_count\n      @page_count ||= Pdfium.FPDF_GetPageCount(@document_ptr)\n    end\n\n    def encrypted?\n      Pdfium.FPDF_GetSecurityHandlerRevision(@document_ptr) >= 0\n    end\n\n    def form?\n      Pdfium.FPDF_GetFormType(@document_ptr) != Pdfium::FORMTYPE_NONE\n    end\n\n    def import_pages(src_doc, pages: nil, index: nil)\n      ensure_not_closed!\n\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)","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/lib/pdfium.rb#L553-L589","documentation":"Pdfium::Document#import_pages wraps FPDF_ImportPages from the PDFium C API and raises PdfiumError 'Failed to import pages' when the native call returns 0. Failure means the requested pages could not be inserted into the destination document: an invalid page specification string, an out-of-range page number, a source document that is closed or cannot yield pages (corrupt or extraction-restricted), or FFI marshalling problems after a pdfium upgrade. The subsequent FPDF_ImportAcroForm call only runs on success.","triggerScenarios":"Passing a pages string like '0', or '5' for a 3-page source, or a malformed range; src_doc already closed (only the destination's ensure_not_closed! is checked here); merging secured or encrypted PDFs that forbid extraction; pdfium library version drift changing argument expectations.","commonSituations":"Template merge features with user-supplied page ranges; password-protected or permissions-locked PDF uploads; upgrading the pdfium binary without re-checking bindings; corrupted uploads that open but fail deep operations.","solutions":["Log the pages argument, both documents' page_count, and encryption status right before the call, and validate the 1-based range.","Ensure both documents are open and readable - import from a freshly opened source when in doubt.","Reproduce outside the app with qpdf or pdfium tooling on the same file pair to confirm the documents themselves merge.","Repair/normalize inputs first (e.g. qpdf --decrypt or a re-save) and retry.","After pdfium upgrades, verify the FPDF_ImportPages signature and string marshalling in the FFI layer."],"exampleFix":"# before\nresult = doc.import_pages(src_doc, pages: params[:pages])\n\n# after\npages = params[:pages].to_s\nif pages.present?\n  nums = pages.scan(/\\d+/).map(&:to_i)\n  raise ArgumentError, 'page out of range' if nums.any? { |n| n < 1 || n > src_doc.page_count }\nend\nresult = doc.import_pages(src_doc, pages: pages.presence)","handlingStrategy":"validation","validationCode":"pages = params[:pages].to_s\nif pages.present?\n  nums = pages.scan(/\\d+/).map(&:to_i)\n  raise ArgumentError, 'page out of range' if nums.any? { |n| n < 1 || n > src_doc.page_count }\nend\ndoc.import_pages(src_doc, pages: pages.presence)","typeGuard":null,"tryCatchPattern":"begin\n  doc.import_pages(src_doc, pages: pages)\nrescue Pdfium::PdfiumError => e\n  mark_merge_failed(document_id)\n  Rails.logger.error(\"import_pages failed: #{e.message} pages=#{pages}\")\nend","preventionTips":["Validate page ranges at the API boundary","Normalize or repair uploaded PDFs before merging","Keep the pdfium binary and FFI bindings version-locked"],"tags":["pdf","pdfium","ffi","merge","import-pages"],"backgroundTag":"pdf-processing-failed","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}