Ask Anvil

The cause

PDF form fields store their visible rendering as a separate appearance stream inside each field widget. Chrome, Firefox, and most browsers will compute that appearance on the fly if it is missing. Adobe Reader (and many mobile PDF viewers) will not. If a tool fills the AcroForm value but never regenerates the appearance stream, Reader shows the field as blank because the cached appearance is still empty.

Fix 1: Set NeedAppearances to true

The simplest fix is to set one flag at the AcroForm dictionary level, which tells any conforming reader to regenerate appearances when the file opens. In Python with pikepdf:

import pikepdf

with pikepdf.open("filled.pdf", allow_overwriting_input=True) as pdf:
    if "/AcroForm" in pdf.Root:
        pdf.Root["/AcroForm"]["/NeedAppearances"] = True
    pdf.save()

In Node with pdf-lib:

import { PDFDocument, PDFBool, PDFName } from 'pdf-lib'

const pdfDoc = await PDFDocument.load(bytes)
const form = pdfDoc.getForm()
form.acroForm.dict.set(PDFName.of('NeedAppearances'), PDFBool.True)
const updated = await pdfDoc.save()

Fix 2: Regenerate the appearance streams

If you control the PDF library, ask it to regenerate appearance streams during fill so every viewer sees the value. Apache PDFBox exposes acroForm.refreshAppearances() for this. pdf-lib will update field appearances when you save, and you can call form.updateFieldAppearances() explicitly before saving. iText also exposes appearance regeneration; consult your version's API docs for the exact method name.

Fix 3: Flatten the PDF

If the recipient does not need to edit the fields, flatten the form. Flattening removes the editable widget and bakes the field value into the static page content, so every reader shows the same thing. pdf-lib offers form.flatten() in Node, and pikepdf supports flattening in Python. Caveat: once flattened, values cannot be edited back into form fields, so flatten only when the document is final.

When NeedAppearances is not enough

NeedAppearances only works when the viewer cooperates with the flag. If end users print or export from a non-conforming reader, blanks can still appear. For high-stakes documents (legal filings, signed agreements, archived records), flatten before delivery so the rendered output is identical in every viewer.