Short answer: Most Docassemble problems fall into five areas: DOCX templates (Jinja2 errors, dates, images), PDF form filling (field names, checkboxes, signatures), Docker upgrades and deployment (data storage, HTTPS, memory), email (mail configuration, default sender, send_email()), and testing (interview paths and generated documents). Find your symptom in the table below and open the matching guide.
This hub links our Docassemble troubleshooting series. Each guide uses a symptom → cause → fix format based on the official docassemble documentation. It’s written for legal aid, court-form and law-firm teams in the USA, UK and Australia.
Note: code and configuration in the linked guides are examples based on the official docassemble documentation. Test them on a staging server before using them in production.
Which guide do you need?
| Problem area | Typical symptom | Guide |
|---|---|---|
| DOCX templates | Jinja2 syntax error, blank fields, unformatted dates, missing images or signatures | DOCX template errors |
| PDF form filling | Fields, checkboxes or signatures don’t populate, or users can still edit the PDF | PDF fill problems |
| Docker upgrades and deployment | Container won’t start after an upgrade, lost data, ignored environment variables, HTTPS failures | Docker upgrade and deployment problems |
No email sent, password resets fail, send_email() returns False, attachments missing | Email not sending | |
| Testing and QA | Every screen works but the generated document is missing a clause or has a broken layout | Testing interviews and documents |
| Ongoing support | Problems keep coming back after launch: updates, backups, security, integrations | Maintenance and support |
Docassemble DOCX template errors
Most DOCX template errors come from five things: Jinja2 tags that Word has split or mis-typed, conditionals and loops that don’t use the p or tr prefixes, dates printed without a format, images mixed with text in one tag, and variables that are undefined when the document is assembled. The guide also covers include_docx_template formatting issues, line breaks in a single field, ampersands breaking Jinja2 code, resizing images and the “expected lxml.etree._Element, got NoneType” error.
Read: Docassemble DOCX template errors: causes and fixes →
Docassemble PDF fill problems
When a 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. The guide covers checkbox values, putting one signature on several pages, uploaded images, stopping users editing the filled PDF, and choosing between PDF and DOCX templates.
Read: Docassemble PDF fields not filling? Causes and fixes →
Docassemble Docker upgrade and deployment problems
Most Docker problems come from a system upgrade done without persistent data storage, a container stopped too quickly, a stale cached image, configuration in storage that silently overrides new environment variables, or a server with too little memory or disk. The guide explains the difference between a package upgrade and a system upgrade, how to upgrade safely, Let’s Encrypt and HTTPS fixes, and whether to pin an image version.
Read: Docassemble Docker upgrade and deployment problems →
Docassemble email not sending
Email failures usually come from a missing or incomplete mail section in the Configuration (no default sender, or wrong SMTP server, port or TLS settings), SMTP being slowed or blocked by your host, or code that ignores what send_email() returns. The guide covers Mailgun and SendGrid HTTP APIs, EU Mailgun URLs, attachments, sending from background processes and email-to-interview.
Read: Docassemble email not sending? Causes and fixes →
How to test Docassemble interviews and generated documents
Testing has to cover both the interview and the document it produces. The guide recommends defining expected results first, checking branches and changed answers manually, comparing document values and clauses against your test inputs, visually inspecting PDF and DOCX output, and adding automated browser tests and regression testing before every release. Use synthetic data so test files never expose client information.
Read: How to test Docassemble interviews and generated documents →
Docassemble maintenance and support
If the same problems keep coming back, you may need a maintenance plan rather than a one-off fix. The guide covers releasing updates safely, interview and template reviews, security, proving you can restore a backup, hosting performance and keeping API integrations working. It also notes that qualified reviewers should approve substantive changes to legal forms.
Read: Docassemble maintenance and support →
FAQ
Where should I start when a Docassemble interview breaks?
Start with the symptom. If the document output is wrong, go to the DOCX or PDF guide. If the server or container fails, go to the Docker guide. If messages don’t arrive, go to the email guide.
Why does a Docassemble document have blank fields?
In DOCX templates, check for Jinja2 tags that Word has split and for variables that are undefined at assembly time. In PDF templates, check that field names exactly match the PDF.
Why did my data disappear after a Docassemble upgrade?
Usually because a system upgrade was done without persistent data storage. Set up data storage before upgrading anything.
Does send_email() returning True mean the email was delivered?
No. It only means no error stopped the hand-off to the mail server. Confirm delivery in your provider’s logs.
How do I stop these problems reaching users?
Test the interview paths and the generated documents before every release, and rerun regression tests whenever logic, templates, dependencies or server settings change.
Need help with a Docassemble problem?
Get a free Docassemble audit of your interviews, templates or server, or see our Docassemble maintenance and support service for ongoing help.