{"record":{"id":"610e63e1b775a614","repo":"docusealco/docuseal","slug":"failed-to-flatten-page-page-index","errorCode":null,"errorMessage":"Failed to flatten page #{page_index}","messagePattern":"Failed to flatten page #(.+?)","errorType":"exception","errorClass":"Pdfium::PdfiumError","httpStatus":null,"severity":"error","filePath":"lib/pdfium.rb","lineNumber":1793,"sourceCode":"\n      l_ptr, b_ptr, r_ptr, t_ptr = Array.new(4) { FFI::MemoryPointer.new(:float) }\n\n      left, bottom, right, top = box.map(&:to_f)\n\n      if Pdfium.FPDFPage_GetMediaBox(page_ptr, l_ptr, b_ptr, r_ptr, t_ptr).zero?\n        Pdfium.FPDFPage_SetMediaBox(page_ptr, left, bottom, right, top)\n      end\n\n      if Pdfium.FPDFPage_GetCropBox(page_ptr, l_ptr, b_ptr, r_ptr, t_ptr).zero?\n        Pdfium.FPDFPage_SetCropBox(page_ptr, left, bottom, right, top)\n      end\n\n      result = Pdfium.FPDFPage_Flatten(page_ptr, flag)\n\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","sourceCodeStart":1775,"sourceCodeEnd":1811,"githubUrl":"https://github.com/docusealco/docuseal/blob/004a22c1c88109c7ba0b567df011a8cb13894001/lib/pdfium.rb#L1775-L1811","documentation":"Raised by Pdfium::Page#flatten (lib/pdfium.rb:1793) when FPDFPage_Flatten returns FLATTEN_FAIL (0). Flattening bakes annotations and form-field appearances into the page content stream; PDFium refuses when the page's annotation or widget tree is malformed, or the document is otherwise uneditable. Pdfium.check_last_error runs first, so if PDFium recorded a reason it raises the richer message; this generic raise covers the case where the failure left no error code.","triggerScenarios":"Calling flatten on a page containing broken annotation appearance streams or widget XObjects; flattening an encrypted / permissions-restricted document opened without full access; calling flatten on a page whose handle was closed; flag set to FLAT_NORMALDISPLAY on pages whose annotations only carry print appearances.","commonSituations":"Signing/completion pipelines that flatten before download; templates built from third-party PDF editors (dragged-in widgets with missing /AP dicts); owner-password-locked PDFs uploaded as templates; running flatten twice or after rotate triggered a reload on a shared page handle.","solutions":["Retry once with flag = Pdfium::FLAT_PRINT (print appearances) instead of the default FLAT_NORMALDISPLAY.","Re-save or repair the source PDF (e.g. re-render it through a clean save) before flattening; broken annotation dictionaries are the most common cause.","Load the document with its password / full permissions before flattening; encrypted docs cannot be edited.","Rescue Pdfium::PdfiumError per page and ship the un-flattened page rather than failing the whole document download."],"exampleFix":"# before\npage.flatten\n\n# after\nbegin\n  page.flatten(Pdfium::FLAT_NORMALDISPLAY)\nrescue Pdfium::PdfiumError\n  page.flatten(Pdfium::FLAT_PRINT)\nend","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"begin\n  page.flatten(Pdfium::FLAT_NORMALDISPLAY)\nrescue Pdfium::PdfiumError\n  begin\n    page.reload rescue Pdfium::PdfiumError # page may be poisoned after failed flatten\n    page.flatten(Pdfium::FLAT_PRINT)\n  rescue Pdfium::PdfiumError => e\n    Rails.logger.warn(\"flatten skipped page #{page.page_index}: #{e.message}\")\n  end\nend","preventionTips":["Open password-protected PDFs with credentials before flattening.","Repair/re-save third-party PDFs whose annotation widgets lack appearance streams.","Flatten each page independently so one bad page cannot abort the whole document.","Do not call flatten on a closed page; ensure_not_closed! guards it but keep lifecycles explicit."],"tags":["pdf","pdfium","flatten","annotations","ffi"],"backgroundTag":"pdf-flatten-failed","analyzedSha":"004a22c1c88109c7ba0b567df011a8cb13894001","analyzedAt":"2026-08-21T13:38:23.343Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}