{"record":{"id":"4f375d5176d3625c","repo":"docusealco/docuseal","slug":"failed-to-reload-page-page-index","errorCode":null,"errorMessage":"Failed to reload page #{page_index}","messagePattern":"Failed to reload page #(.+?)","errorType":"exception","errorClass":"Pdfium::PdfiumError","httpStatus":null,"severity":"error","filePath":"lib/pdfium.rb","lineNumber":1807,"sourceCode":"\n      if result == Pdfium::FLATTEN_FAIL\n        Pdfium.check_last_error(\"Failed to flatten page #{page_index}\")\n\n        raise PdfiumError, \"Failed to flatten page #{page_index}\"\n      end\n\n      reload if result == Pdfium::FLATTEN_SUCCESS\n\n      result\n    end\n\n    def reload\n      close_page_view\n      Pdfium.FPDF_ClosePage(@page_ptr)\n\n      @page_ptr = Pdfium.FPDF_LoadPage(@document.document_ptr, @page_index)\n\n      raise PdfiumError, \"Failed to reload page #{page_index}\" if @page_ptr.null?\n\n      @page_view = false\n      @rotation = nil\n      @width = nil\n      @height = nil\n      @box = nil\n\n      @document.reset_annot_count(@page_index)\n\n      reset_memoization\n    end\n\n    def close\n      return if closed?\n\n      unless @page_ptr.null?\n        close_page_view\n","sourceCodeStart":1789,"sourceCodeEnd":1825,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/lib/pdfium.rb#L1789-L1825","documentation":"Raised by Pdfium::Page#reload (lib/pdfium.rb:1807) when FPDF_LoadPage returns NULL after the old page handle was already closed with FPDF_ClosePage. reload is called internally after successful flatten and rotate, so this error means the page became unopenable mid-operation: the parent document handle is closed/freed, the in-memory document was corrupted by the preceding mutation, or the page index no longer resolves. Because the old handle is already destroyed, the page object is unusable after this raise.","triggerScenarios":"reload triggered by a successful flatten/rotate while another thread called close on the document or page (concurrent access to the FFI handle); in-memory PDF buffer freed (source_buffer garbage collected on the Document) before reload; document dictionary damaged by the transform so FPDF_LoadPage rejects the page; @page_index out of range after document mutation.","commonSituations":"Multi-threaded PDF processing where pages of one document are shared across threads (PDFium handles are not thread-safe); long-running jobs that flatten many pages while a watchdog closes the document on timeout; rare PDFs whose page tree breaks after TransFormWithClip.","solutions":["Process a document (and its pages) from a single thread; never share Pdfium::Document/Page handles across threads.","Rescue PdfiumError from flatten/rotate, then rebuild from scratch: close the document, re-load it from the original bytes, and return the fresh page instead of the poisoned one.","Keep a reference to the source buffer for the whole document lifetime so the in-memory document stays valid through reload.","If it reproduces on one specific file, extract that page into a standalone PDF and re-run to isolate a corrupt page tree."],"exampleFix":"# before\npage.flatten\npage.text_objects\n\n# after\nbegin\n  page.flatten\nrescue Pdfium::PdfiumError\n  doc = Pdfium.open_document(original_bytes)\n  page = doc.page(page.index) # fresh handles after failed reload\nend\npage.text_objects","handlingStrategy":"fallback","validationCode":"# Before mutating (flatten/rotate), confirm the document handle is still open\nraise ArgumentError, 'document closed' if document.closed?","typeGuard":null,"tryCatchPattern":"begin\n  page.flatten # may internally reload\nrescue Pdfium::PdfiumError\n  # old page handle is destroyed after a failed reload — rebuild from source\n  document.close\n  document = Pdfium.open(original_bytes)\n  page = document.page(index)\nend","preventionTips":["One thread per document; never share Document/Page handles across threads.","Retain the original PDF bytes so any page can be rebuilt after a failed reload.","Treat a failed reload as poisoning the whole in-memory document — reopen rather than retry the page.","Guard mutating sequences (rotate -> flatten) with a single ownership context."],"tags":["pdf","pdfium","ffi","concurrency","page-handle"],"backgroundTag":"pdf-page-load-failed","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}