My PDF form fields are not filling correctly, how do I debug this?

Here’s a practical way to debug PDF form-filling issues.

1) First identify the type of PDF form

There are two common kinds:

• AcroForm: regular fillable PDF fields
• XFA: dynamic forms, often from older Adobe workflows

Why this matters:

• Many libraries handle AcroForms well.
• XFA support is limited in many tools.
• If a PDF looks fillable in Adobe Reader but not in your library, it may be XFA.

2) Inspect the form field names

A very common issue is that the field names you’re writing to do not match the actual PDF field names.

Check:

• exact field name
• nested names like address.street
• case sensitivity
• duplicate fields with same name
• hidden fields / read-only fields

Tools to inspect field names

• Adobe Acrobat Pro: prepare form mode
• pdftk: dump_data_fields
• pdfcpu
• Python libraries: pypdf, PyMuPDF, etc.

Example with pypdf:

from pypdf import PdfReader

reader = PdfReader("form.pdf")
fields = reader.get_fields()
print(fields.keys())

3) Verify the field type

Different field types need different handling:

• text field
• checkbox
• radio button
• dropdown / combo box
• list box
• signature field

Common mistakes:

• writing "Yes" to a checkbox when the export value is something else
• setting a radio button to a label instead of its internal value
• using text-filling logic for dropdowns

4) Check whether appearances are being regenerated

A filled field may have the correct value internally, but still render blank in some viewers unless appearance streams are updated.

Symptoms:

• data is present if you inspect field values programmatically
• field looks blank in the PDF viewer

Fixes:

• regenerate appearances
• set “need appearances” flags depending on your library
• open/save in Adobe Acrobat if needed
• flatten the form as a fallback

For pypdf, sometimes you need:

writer.update_page_form_field_values(page, fields)

and/or set appearance-related flags depending on workflow.

5) Confirm the viewer isn’t hiding the issue

Some PDF viewers are more forgiving than others.

Test the output in:

• Adobe Acrobat Reader
• Chrome/Edge built-in PDF viewer
• Foxit or another PDF reader

If it works in Acrobat but not browser viewers, it’s often an appearance-stream issue.

6) Make sure the page/form structure hasn’t changed

If fields were added manually or a template changed:

• the field may be on a different page
• the annotation might be deleted but the field dictionary remains
• the page rotation may be off
• an overlay may obscure the field visually

7) Debug with a minimal script

Try filling just one field first.

Example in Python with pypdf:

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()
writer.append_pages_from_reader(reader)

writer.update_page_form_field_values(writer.pages[0], {"Name": "Alice"})

with open("output.pdf", "wb") as f:
    writer.write(f)

Then confirm:

• the output file opens
• the field name is correct
• the value appears

8) Flatten as a diagnostic step

If filling works internally but not visually, flattening can prove the data is there.

Flattening:

• converts fields into static page content
• prevents further editing
• often fixes appearance problems

If flattening makes it show up, your issue is likely appearances, not field assignment.

9) Compare before/after structure

Use a PDF inspection tool to compare:

• field dictionaries
• widget annotations
• /V value
• /AP appearance streams
• /NeedAppearances

If you see:

• /V set but no /AP: appearance issue
• wrong /T: field name issue
• /Kids or widget annotations not where expected: structure issue

10) Common gotchas

• Checkbox export value is not "On" in all PDFs
• Need to use the exact radio choice key
• Some fields are locked/read-only
• Signature fields can’t be filled like text fields
• Encrypted PDFs may require permissions
• Form is an XFA form unsupported by your library
• The document uses embedded JavaScript that changes field behavior

11) Best debugging workflow

1. Print all field names and values from the input PDF
2. Fill exactly one field
3. Re-open output in Adobe Reader
4. Inspect whether the internal value changed
5. If value changed but not visible, fix appearances or flatten
6. If value didn’t change, check the field name/type/export value

12) If you tell me your stack, I can be more specific

If you share:

• language/library you’re using
• sample code
• whether it’s AcroForm or XFA
• what “not filling correctly” means:
  • blank output?
  • wrong field?
  • checkbox/radio not selected?
  • text invisible?

I can give you a targeted debugging checklist and code example.