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