[syncfusion_flutter_pdfviewer 33.2.6] Filled AcroForm widgets on Quartz-authored PDF 1.4 render as blank page (no exception, no console output)

[iamku7sh]

Bug description

SfPdfViewer silently renders a blank white page for PDF files that:

1. Were originally authored by macOS Quartz (/Producer (macOS … Quartz PDFContext)), producing a PDF 1.4 AcroForm with AcroForm.DR = null
2. Have any text-field widget with a non-empty /V (filled value)

The viewer shows no error, throws no exception, prints nothing to the console. The page is just blank. The same PDFs render correctly in every other PDF viewer I've tested:

• pdfx (Flutter, PDFium-backed) — renders correctly
• Adobe Acrobat Reader — renders correctly
• Google Chrome (built-in PDF viewer) — renders correctly
• macOS Preview / PDFKit — renders correctly

Unfilled versions of the same template do render in SfPdfViewer once /AcroForm/DR/Font is populated. The trigger is specifically setting /V on any widget — not the appearance stream, not the PDF version, not the fill library. I verified this across 13 structural variants (matrix below).

This is a new defect distinct from previously-closed similar issues (#1988, #223) — those samples render fine in 33.2.6.

Steps to reproduce

The smallest failing case is single_widget_v_only.pdf — the original Quartz-authored AcroForm template with /V (TEST) set on exactly one text widget. No /AP, no /DA change, no other modifications. /AcroForm/DR/Font/Helv is present and resolves to standard Type1 Helvetica.

Producing this PDF from any compliant PDF library reproduces the bug. Example with PyMuPDF (same shape with pikepdf, qpdf, pypdf — all fail identically):

import fitz

doc = fitz.open("original_template.pdf")

# Add /AcroForm/DR/Font/Helv (standard 14 Helvetica Type1)
helv_xref = doc.get_new_xref()
doc.update_object(helv_xref, """<<
  /Type /Font
  /Subtype /Type1
  /BaseFont /Helvetica
  /Encoding /WinAnsiEncoding
>>""")
dr_xref = doc.get_new_xref()
doc.update_object(dr_xref, f"<<\n/Font << /Helv {helv_xref} 0 R >>\n>>")
catalog = doc.pdf_catalog()
af = doc.xref_get_key(catalog, "AcroForm")
form_xref = int(af[1].split()[0])
doc.xref_set_key(form_xref, "DR", f"{dr_xref} 0 R")

# Set /V on a single text widget — nothing else
for page in doc:
    for w in page.widgets() or []:
        if w.field_type_string == "Text" and w.field_name == "FirstName":
            doc.xref_set_key(w.xref, "V", "(TEST)")
            doc.xref_set_key(w.xref, "AP", "null")  # force regen
            break
    break
doc.xref_set_key(form_xref, "NeedAppearances", "true")
doc.save("filled_single_widget.pdf", garbage=3, deflate=True)

Open filled_single_widget.pdf in SfPdfViewer.asset(...) → blank page. Open the same file in any other viewer → renders fine.

Code sample

import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_pdfviewer/pdfviewer.dart';

void main() => runApp(const MaterialApp(home: Scaffold(
  body: SfPdfViewer.asset('assets/filled_single_widget.pdf'),
)));

Screenshots or Video

issue_recording.mov

filled_dr_no_ap.pdf
filled_dr_pdf17.pdf
filled_pikepdf_v14.pdf
filled_pikepdf.pdf
filled_post_autoshrink.pdf

Stack Traces

Stack Traces

[Add the Stack Traces here]

On which target platforms have you observed this bug?

Web (iOS browser)

Flutter Doctor output

Doctor output

[✓] Flutter (Channel stable, 3.38.5, on macOS 26.3.1 25D2128 darwin-arm64, locale en-IN) [403ms]
    • Flutter version 3.38.5 on channel stable at /opt/homebrew/Caskroom/flutter/3.32.5/flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision f6ff1529fd (5 months ago), 2025-12-11 11:50:07 -0500
    • Engine revision 1527ae0ec5
    • Dart version 3.10.4
    • DevTools version 2.51.1
    • Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop,
      enable-android, enable-ios, cli-animations, enable-native-assets, omit-legacy-version-file,
      enable-lldb-debugging

[!] Android toolchain - develop for Android devices (Android SDK version 36.0.0) [882ms]
    • Android SDK at /Users/kamleshuikey/Library/Android/sdk
    • Emulator version 36.1.9.0 (build_id 13823996) (CL:N/A)
    ✗ cmdline-tools component is missing.
      Try installing or updating Android Studio.
      Alternatively, download the tools from
      https://developer.android.com/studio#command-line-tools-only and make sure to set the ANDROID_HOME
      environment variable.
      See https://developer.android.com/studio/command-line for more details.
    ✗ Android license status unknown.
      Run `flutter doctor --android-licenses` to accept the SDK licenses.
      See https://flutter.dev/to/macos-android-setup for more details.

[!] Xcode - develop for iOS and macOS (Xcode 26.2) [1,402ms]
    • Xcode at /Applications/Xcode.app/Contents/Developer
    • Build 17C52
    ! iOS 26.2 Simulator not installed; this may be necessary for iOS and macOS development.
      To download and install the platform, open Xcode, select Xcode > Settings > Components,
      and click the GET button for the required platform.

      For more information, please visit:
        https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes
    • CocoaPods version 1.16.2

[✓] Chrome - develop for the web [5ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Connected device (2 available) [5.8s]
    • macOS (desktop) • macos  • darwin-arm64   • macOS 26.3.1 25D2128 darwin-arm64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 148.0.7778.97

[✓] Network resources [520ms]
    • All expected network resources are available.

! Doctor found issues in 2 categories.
(.venv) ➜  syncfusion_

[iamku7sh]

Root cause located in pdfviewer.dart

syncfusion_flutter_pdfviewer 33.2.6 — _retrieveFormFieldsDetails() throws Null check operator used on a null value at:

// packages/syncfusion_flutter_pdfviewer/lib/src/pdfviewer.dart:1669-1670
final PdfPage? page = _document!.form.fields[i].page;
final int pageIndex = _document!.pages.indexOf(page!);   // ← throws here

The exception is swallowed by the surrounding catch block (~line 2327) because its message doesn't match any of the recognised error strings — no onDocumentLoadFailed callback fires, the page renderer is never initialised, and the user sees a blank white page with no console output.

When does field.page return null?

When the input PDF's AcroForm.Fields[i] entry and its matching page.Annots[j] widget annotation have diverged to different xrefs — common after any third-party library (PyMuPDF, pikepdf, etc.) modifies a combined field+widget AcroForm and saves. In our case:

• AcroForm.Fields[i] → xref A (has /FT, /T, sometimes /Subtype /Widget, no /V)
• page.Annots[j] → xref B (has /V, /DA, /AP, /Rect)

_getLoadedPage() in pdf_field.dart:

1. widget.containsKey(/P) → false (Quartz-authored templates often omit /P)
2. falls back to walking doc.pages[*].Annots[*] looking for a PdfReferenceHolder whose objNum/genNum match the field's widget reference
3. xref A's widget reference is not found in any page's annot list (page.Annots only contains xref B) → walk completes without a match → returns null

Reproduction

syncfusion_flutter_pdf itself does NOT trigger this on a PDF it generated — only files generated by other PDF libraries that split combined field+widget dicts. Tested with PyMuPDF 1.x and pikepdf/qpdf — both produce equivalent splits.

Minimal failing PDF: any Quartz-authored AcroForm template (e.g. macOS Preview "Tools → Show Form Editor → Add Text Field") with a single text field, filled via:

import fitz  # PyMuPDF
doc = fitz.open("template.pdf")
for w in doc[0].widgets():
    w.field_value = "TEST"
    w.update()
doc.save("filled.pdf")

filled.pdf opens correctly in Adobe Reader, Chrome, macOS Preview/PdfKit but renders blank in SfPdfViewer.

Larger repro with multiple variants (DR added, AP stripped, PDF 1.7, etc.) available on request — every variant where any widget has /V set fails identically.

Suggested fixes (in priority order)

1. Null-guard the call site (one-liner)

// pdfviewer.dart:1669
final PdfPage? page = _document!.form.fields[i].page;
if (page == null) {
  // Skip this field — its widget annotation can't be matched to a page.
  // Log a warning so users can diagnose, but don't abort the entire page render.
  continue;
}
final int pageIndex = _document!.pages.indexOf(page);

Even if field.page returns null because of upstream PDF quirks, the loss of editability for ONE field is much better than the whole document failing to render with no error.

2. Make the outer catch loud (~pdfviewer.dart:2327)

} catch (e, st) {
  // Always log unmatched errors so silent failures are diagnosable.
  log.severe('SfPdfViewer document load failed', e, st);
  // ... existing pattern matching
}

The current if/else if chain only matches four specific error strings. Any other exception is dropped without trace.

3. Add a /T-name fallback to _getLoadedPage() in pdf_field.dart

When the reference-walk fails to match by xref, walk pages.Annots again and match by /T (field name). This handles the field/widget xref-divergence case that's common with multi-library PDF pipelines.

Workaround we shipped (for others hitting this)

We restore the spec-canonical structure on the backend after PyMuPDF fills the form: ONE combined field+widget dict per field, referenced from both AcroForm.Fields and page.Annots. Same shape the original templates had before PyMuPDF split them. With this in place, the existing _getLoadedPage() reference-walk in pdf_field.dart succeeds without any viewer-side change.

The post-fill Python (PyMuPDF) looks roughly like:

import fitz

def patch_for_syncfusion(doc: fitz.Document) -> None:
    cat = doc.pdf_catalog()
    af_ref = doc.xref_get_key(cat, "AcroForm")
    if af_ref[0] != "xref":
        return
    form_xref = int(af_ref[1].split()[0])

    # 1. Default /DR/Font/Helv so widget DAs referencing /Helv resolve when
    #    appearances regenerate.
    _ensure_default_helvetica(doc, form_xref)

    # 2. Index every page.Annots widget by /T name.
    widgets_by_name: dict[str, int] = {}
    for page in doc:
        for w in page.widgets() or []:
            if w.field_name and w.field_name not in widgets_by_name:
                widgets_by_name[w.field_name] = w.xref

    # 3. For each leaf AcroForm.Fields entry whose /T matches a page.Annots
    #    widget at a different xref:
    #       - Copy /FT and /Ff to the widget if absent (so the widget becomes
    #         a complete combined field+widget dict).
    #       - Rewrite Fields[i] to point at the widget xref.
    #    Leaf-only: skip entries with /Kids (parent fields with children
    #    must keep their tree intact).
    fields_ref = doc.xref_get_key(form_xref, "Fields")
    refs = fields_ref[1].strip("[] ").split()
    field_xrefs = [int(refs[i]) for i in range(0, len(refs), 3)]
    new_fields: list[int] = []
    for fx in field_xrefs:
        t = doc.xref_get_key(fx, "T")
        name = t[1] if t[0] == "string" else None
        if (not name or name not in widgets_by_name
                or doc.xref_get_key(fx, "Kids")[0] != "null"):
            new_fields.append(fx)
            continue
        widget_xref = widgets_by_name[name]
        if widget_xref == fx:
            new_fields.append(fx)
            continue
        for key in ("FT", "Ff"):
            if doc.xref_get_key(widget_xref, key)[0] == "null":
                src = doc.xref_get_key(fx, key)
                if src[0] != "null":
                    doc.xref_set_key(widget_xref, key, src[1])
        new_fields.append(widget_xref)
    doc.xref_set_key(
        form_xref, "Fields",
        "[ " + " ".join(f"{x} 0 R" for x in new_fields) + " ]",
    )

After this runs, Syncfusion renders the filled PDF correctly with values visible and form editing functional. Adobe / Chrome / Preview / PDFium-backed viewers continue rendering unaffected — the structure is just the standard combined-dict pattern, which they all already handle.

If _getLoadedPage() is hardened upstream (suggestion #3 above — /T-name fallback after the reference walk fails), this workaround becomes unnecessary and we'll remove it on our end.

---

Environment

• syncfusion_flutter_pdfviewer: 33.2.6 (latest as of 2026-05-14)
• Flutter 3.38.5, Dart 3.10.4
• Reproduces on macOS desktop (debug + release), should reproduce on web/iOS/Android since SfPdfViewer is pure-Dart
• Originating PDF: macOS Quartz-authored AcroForm 1.4, filled via PyMuPDF 1.x

[AbinayaSF4962]

Hi @iamku7sh ,

We are able to reproduce the issue where SfPdfViewer renders a blank page for certain PDFs authored by macOS Quartz (PDF 1.4 AcroForm with AcroForm.DR = null) when any text-field widget has a non-empty /V value. We are currently validating this issue and will provide further updates on May 19, 2026.

Regards,
Abinaya E

[AbinayaSF4962]

Hi @iamku7sh ,
We have confirmed that the issue where SfPdfViewer renders blank page for Quartz-generated PDFs with filled AcroForm fields is a defect in our product and logged a bug report for the same. The fix for this issue will be included in the weekly release scheduled for June 02, 2026.

Please use the feedback link to track the status of the bug, SfPdfViewer renders blank page for Quartz-generated PDFs with filled AcroForm fields in Flutter | F…

Disclaimer: "Inclusion of this solution in the weekly release may change due to other factors including but not limited to QA checks and works reprioritization."

Regards,
Abinaya E