docusealco/docuseal · error · Pdfium::PdfiumError

Failed to load text page

Error message

Failed to load text page

What it means

Raised inside Page#redact via remove_redacted_chars when FPDFText_LoadPage returns NULL for the page being redacted. Unlike the Page#text variant there is no check_last_error and no page index in the message. unwrap_form_objects has already run when this fires, so the page is partially modified; re-open the document before any save rather than persisting the half-edited state.

Source

Thrown at lib/pdfium.rb:1216

          content = buffer.read_bytes(written - 2).force_encoding('UTF-16LE').encode('UTF-8')

          blanks << object_ptr if content.codepoints.all? { |code| BLANK_TEXT_CODEPOINTS.include?(code) }
        end
      ensure
        Pdfium.FPDFText_ClosePage(text_page)
      end

      return if blanks.empty?

      blanks.each { |object_ptr| remove_page_object(object_ptr) }

      Pdfium.FPDFPage_GenerateContent(@page_ptr)
    end

    def remove_redacted_chars(rect_bounds)
      text_page = Pdfium.FPDFText_LoadPage(@page_ptr)

      raise PdfiumError, 'Failed to load text page' if text_page.null?

      begin
        text_objects_chars = collect_text_objects_chars(text_page, rect_bounds)
      ensure
        Pdfium.FPDFText_ClosePage(text_page)
      end

      text_objects_chars.each_value do |entry|
        next if entry[:chars].none? { |char| char[:redacted] }

        rebuild_text_object_survivors(entry) unless entry[:chars].all? { |char| char[:redacted] }

        remove_page_object(entry[:ptr])
      end
    end

    def unwrap_form_objects(rect_bounds = nil)
      unwrapped = false

View on GitHub (pinned to 004a22c1c8)

Solutions

1. Pre-screen with page.text (rescuable) and skip redaction for pages that cannot build a text page
2. Re-open the original and retry once
3. Repair the PDF (qpdf or ghostscript) before redaction
4. For scan-only pages, use a draw-only fallback that paints opaque rects without character surgery

Example fix

# before
page.redact(rects)

# after - skip pages whose text layer cannot even load
begin
  page.text # pre-screen: same underlying FPDFText_LoadPage
rescue Pdfium::PdfiumError
  next # or draw-only fallback
end
page.redact(rects)

begin
  page.text # same FPDFText_LoadPage call the redact path uses
rescue Pdfium::PdfiumError
  return skip_or_flag_page(page)
end
page.redact(rects)

begin
  page.redact(rects)
rescue Pdfium::PdfiumError => e
  raise unless e.message == 'Failed to load text page'
  page_redact_draw_only(page, rects) # opaque rects, no char surgery
end

When it happens

Trigger: Calling redact on a page with an unparseable text layer or corrupt content stream; redacting a page whose form unwrapping left its content stream inconsistent.

Common situations: Bulk redaction over heterogeneous user uploads where a few files are damaged; redacting previously-redacted documents.

Related errors

• Failed to load text page #{page_index}, pointer is NULL.
• Failed to load page #{page_index}, pointer is NULL.
• Failed to generate page content
• Failed to unwrap form object
• Failed to remove page object

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