Short answer: When a Docassemble pdf template file doesn’t fill, the cause is nearly always a field name that doesn’t exactly match the PDF, a signature field that shares its name with another field, a value passed in the wrong form, or a PDF that needs pdftk rather than the default pikepdf filler. Check field names first.
Court and tribunal forms in the USA, UK and Australia are often supplied as fillable PDFs, so PDF filling is central to legal aid and court-form projects. This guide uses a symptom → cause → fix format, based on the official docassemble Documents docs and real GitHub issues.
Note: the code and commands below are examples based on the official docassemble documentation. Test them on a staging server before using them in production.
Quick diagnostic table
| Symptom | Likely cause | Fix |
|---|---|---|
| A field stays empty | Name doesn’t match the PDF exactly | Get the exact names from Utilities and copy them |
| Signature missing | Not a “Digital Signature” field, or duplicate field names | One uniquely named signature field per spot |
| Same signature needed on several pages | Fields share one name | Give each field a different name, pass the same variable |
| Uploaded photo or image doesn’t appear, or lands in the wrong box | Image needs its own uniquely named “Digital Signature” field; older versions had a bug (#602) | One “Digital Signature” field per image; upgrade to 1.4.24 or later |
'str' object has no attribute 'signature' |
The variable is a string, not an object | Make the parent an object (e.g. Individual) |
| Checkboxes not ticked | Value isn’t a true/false answer | Pass a yes/no variable |
| Users can still edit the output | Default: output stays editable | editable: False |
| Odd rendering with some forms | Filler library differences | Try pdftk: True |
Why aren’t my PDF fields filling in Docassemble?
Answer: The keys under fields must match the PDF’s field names exactly, including spaces and capitals. Many government forms have long or auto-generated names. Log in as a developer, open Utilities, and use “Get list of fields from PDF/DOCX template” to get the literal names, then copy them into your YAML.
attachment:
name: A filled-in form
filename: filled-form
pdf template file: sample-form.pdf
fields:
- Your Name: |
${ user }
- Your Organization: |
${ user.organization }
The docs say field names “must correspond exactly with the names of the fields in the PDF file” and recommend renaming fields in Adobe Acrobat Pro to concise, meaningful names when a form has many fields (Documents). Note that PDF values are passed with Mako (${ ... }), not Jinja2. Template files are expected in your package’s data/templates folder.
How do you map checkbox values correctly?
Answer: Pass a yes/no variable to each checkbox field, as in the official example Apple Checkbox: ${ likes_apples }. Collect it with a yesno question or a yesno field. If a box still won’t tick, check the field’s name with the Utilities field list and test the PDF with pdftk: True.
fields:
- Apple Checkbox: |
${ likes_apples }
- Orange Checkbox: |
${ likes_oranges }
Source: the sample-form example in Documents. (Editor’s note: forms with unusual checkbox “on” values should be tested on the actual court form before publishing advice specific to them.)
Why does a signature not appear in my PDF template?
Answer: Docassemble inserts images into “Digital Signature” fields. Add a signature field in Acrobat, give it a unique name, and set it to ${ user.signature }. If two fields share a name, Docassemble can’t locate them, so the signature won’t appear. It trims whitespace and fits the image to the box.
question: |
Please sign your name below.
signature: user.signature
under: |
${ user }
---
attachment:
name: Transfer of ownership
filename: Transfer-of-Ownership
pdf template file: Transfer-of-Ownership.pdf
fields:
- "signature": ${ user.signature }
Users have reported signatures failing to fill in GitHub issue #434 and signature or image uploads not populating correctly in issue #602. The unique-name rule is in the Documents docs.
How do you put the same signature on several pages?
Answer: Create a separate “Digital Signature” field for each place, give each a different name, and pass the same variable to all of them. Copying one field across pages in Acrobat gives copies the same name, which stops Docassemble locating them. This is the documented fix for multi-page signatures.
fields:
- first signature: ${ user.signature }
- second signature: ${ user.signature }
- third signature: ${ user.signature }
Related report: GitHub issue #613, same signature in a multi-page PDF template.
Why doesn’t an uploaded image (not a signature) appear in my PDF?
Answer: Docassemble fills images into a PDF the same way it fills signatures: through a “Digital Signature” field. In Adobe Acrobat Pro, add a “Digital Signature” field where the image should go, size it to the image, and give it a unique name. Then pass the uploaded file to it in fields. Docassemble trims whitespace and fits the image into the box.
question: Insurance card - front
fields:
- Picture: card_front
datatype: file
---
attachment:
name: Medical form
filename: medical_form
pdf template file: medical_form.pdf
fields:
- "Signature1": ${ user.signature }
- "CardFront": ${ card_front }
The docs give the same steps “to add a signature or other image to a fillable PDF file” (Documents). In GitHub issue #602, a signature and an uploaded insurance-card image both landed in the last form field. The maintainer fixed it in version 1.4.24, and the reporter confirmed the fix. If you see this on an older server, upgrade.
If the image must flow with text or change size with the content, a PDF form field is the wrong tool. Use a DOCX template instead: see how to resize images in DOCX templates (link live once article 1 is published).
What does “‘str’ object has no attribute ‘signature'” mean?
Answer: It means the variable before .signature is a plain string, not an object. For example, user was set as text rather than created as an Individual. Declare the object in an objects block before you ask for the signature, so user.signature has an object to attach to.
objects:
- user: Individual
Reported in GitHub issue #766.
How do you stop users editing the filled PDF?
Answer: By default the fill-in boxes stay in the output, so users can edit the filled PDF. Set editable: False on the attachment (or give it a Python expression that evaluates to False) to produce a non-editable PDF. Keep a copy of the editable version if staff need to correct forms later.
attachment:
name: A filled-in form
filename: filled-form
pdf template file: sample-form.pdf
editable: False
fields:
Your Name: |
${ user }
Source: “Making PDF files non-editable” in Documents.
When should you use pdftk instead of the default filler?
Answer: Docassemble fills PDF fields with pikepdf by default. If a particular form renders incorrectly, set pdftk: True on the attachment to fill it with pdftk instead, then compare the two outputs. This is useful with older or unusually built government forms.
attachment:
name: A filled-in form
filename: filled-form
pdf template file: sample-form.pdf
pdftk: True
fields:
- Your Name: |
${ user }
Source: “Using pdftk to fill the fields” in Documents.
PDF or DOCX: which template type should you choose?
Answer: Use a fillable PDF when a court or agency requires its exact official form. Use DOCX when the wording, clauses or length change with the user’s answers. Many legal aid projects use both: the PDF for the official filing and a DOCX for cover letters and instructions.
See our companion guide, Docassemble DOCX template errors (link live once article 1 is published).
FAQ
How do I put a photo or uploaded image into a Docassemble PDF?
Add a uniquely named “Digital Signature” field in Adobe Acrobat Pro where the image should go, then set that field to the uploaded file variable, for example CardFront: ${ card_front }. Docassemble fits the image into the box.
Can I fill a scanned PDF that has no form fields?
Not with pdf template file, which needs fillable fields. Add fields in a PDF editor such as Adobe Acrobat Pro first, or rebuild the form as a DOCX template.
Why is a field filled but the text cut off? The text is longer than the field box. Shorten the value in your YAML, reduce the field’s font size in the PDF, or move long text to an addendum.
Can I call functions in PDF field values?
Yes. Each value is a Mako expression, for example letter_date: ${ today() }, as shown in the docs.
Do I need Adobe Acrobat Pro? Not strictly, but the docassemble docs recommend it for giving fields concise, meaningful names, which makes mapping much easier.
Get your court forms tested
Our free Docassemble audit tests your PDF forms end to end, including field mapping, signatures and output settings.
Related reading – Docassemble court forms automation: build court-ready PDFs faster – Generate PDF and DOCX documents in Docassemble – Docassemble document templates: PDF and DOCX formatting that doesn’t break – Docassemble support and maintenance checklist
Sources: docassemble.org — Documents, GitHub jhpyle/docassemble issues #434, #602, #613, #766. Checked 1 Nov 2026.
More in this Docassemble troubleshooting series – Complete Docassemble troubleshooting guide – Docassemble DOCX template errors: causes and fixes – Docassemble Docker upgrade and deployment problems – Docassemble support and maintenance