Short answer: Most Docassemble 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. Each has a predictable fix, set out below.
Docassemble assembles Word documents with a docx template file and the python-docx-template library, which uses a slightly modified Jinja2 syntax (docassemble docs: Documents). That makes it powerful, and also easy to break. This guide follows a symptom → cause → fix pattern for each problem.
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 |
|---|---|---|
| Jinja2 syntax error on assembly | Tag split by Word formatting, or Python syntax Jinja2 doesn’t allow | Retype the tag in one go; use filters instead of Python built-ins |
| Empty paragraphs or broken table rows | {% if %} / {% for %} without p / tr prefix |
Use {%p ... %} on its own line, {%tr ... %} in its own row |
| Date prints in an odd format or errors | Raw date value, no format | Call .format_date() |
| Image missing or document error | Image mixed with text inside {{ }} |
Put the image alone in its own tag; use .show(width=...) |
| Fields come out blank | Variable undefined, or skip undefined hiding it |
Define the variable first; use skip undefined with care |
TypeError: Argument 'element' has incorrect type (expected lxml.etree._Element, got NoneType) |
Small structural errors inside the .docx file | Open the file in Word and save it again, or rebuild it from a fresh document |
& in template code turns into & |
Known issue with ampersands in Jinja2 expressions (closed on GitHub) | Retest on your version; avoid & inside {% %} / {{ }} code |
| Image too large or too small | Image inserted without a width | {{ my_image.show(width="2in") }} |
| Included document loses formatting | include_docx_template() not in {{p ... }} form |
Use the p form on its own line |
Why does my DOCX template throw a Jinja2 error?
Answer: A Jinja2 error usually means the tag itself is malformed. Word often splits a tag across formatting runs when you edit part of it, or autocorrect swaps quotes. Jinja2 also rejects some Python, such as referring to None or calling len(). Retype the tag cleanly and use Jinja2 filters instead of Python built-ins.
Symptom: the interview stops at the attachment step with a template or syntax error.
Cause: Docassemble’s docs note that Jinja2 “does not allow you to write every kind of Python expression” — for example, you can’t refer to None — and it encourages filters instead (Documents: Jinja2 filters).
Fix:
{# Instead of: {{ len(favorite_fruits) }} #}
You have {{ favorite_fruits | length }} favorite fruits.
{# Instead of: {% if result_of_api_call is None %} #}
{% if none(result_of_api_call) %}N/A{% endif %}
Both replacements come from the official documentation. If a tag still fails, delete it and type it again in one go without changing font or style halfway through.
Why do conditionals and loops leave blank lines or break tables?
Answer: Plain {% if %} and {% for %} tags stay inside the paragraph or table row they sit in, so you get empty paragraphs or broken rows. Put paragraph-level logic in {%p ... %} tags on their own lines and table-row logic in {%tr ... %} tags in their own rows. python-docx-template then removes those lines from the output.
Fix — paragraph conditional:
Hello, {{ user }}.
{%p if user.age_in_years() > 30 %}
You cannot be trusted!
{%p endif %}
Fix — table loop (two extra rows in the Word table, one for each tr tag):
| Name | Age |
| {%tr for child in children %} | |
| {{ child }} | {{ child.age_in_years() }} |
| {%tr endfor %} | |
The docs explain that the tr prefix means “process the Jinja2 in this row, but don’t actually include this row in the assembled document” (Documents: tables).
How do you format dates correctly in DOCX templates?
Answer: Store dates with datatype: date so Docassemble gives you a DADateTime object, then format it in the template with .format_date(). Set a default format with the date format language setting if you need one house style. Users report “Bad date” or unexpected output when the stored value isn’t a real date.
Symptom: the date prints as a raw value, in the wrong style, or as “Bad date” (reported in GitHub issue #756; see also #857, dates and template filters).
Fix:
question: When was the agreement signed?
fields:
- Date signed: signing_date
datatype: date
This agreement was signed on {{ signing_date.format_date("MMMM d, yyyy") }}.
For UK and Australian documents, use a day-first pattern such as "d MMMM yyyy". The format_date() function and the date format default are documented in Functions.
How do you insert images and signatures into Word output?
Answer: Put the image variable alone inside its own {{ }} tag, for example {{ user.signature }}, and control its size with .show(width="2in"). Don’t concatenate an image with text in one tag. If the image looks cropped or squashed, check the line spacing of the paragraph it sits in.
Signed: {{ user.signature.show(width="2in") }}
The docs say image references “need to be by themselves inside of {{ }} brackets” and that paragraph spacing can affect how the image appears (Documents). Accessibility of signatures and other inserted images in DOCX output is discussed in GitHub issue #946.
Why does include_docx_template corrupt formatting or cross-references?
Answer: include_docx_template() must be called with the p form of Jinja2 markup, {{p include_docx_template('sub_document.docx') }}, alone on its own line. Otherwise the included paragraphs don’t merge correctly. Cross-references, bookmarks and complex fields in the included file can still break, so test them.
{{p include_docx_template('sub_document.docx') }}
The p-form requirement is in the Documents and Functions docs. Cross-reference corruption is reported in GitHub issue #805. Our practical advice: keep cross-referenced numbering in the main template rather than in included sub-documents.
How do you add line breaks or formatted text in a single field?
Answer: A plain {{ variable }} won’t turn newlines into Word line breaks. Use the RichText filter with the r prefix, {{r variable | RichText }}, or convert Markdown with the markdown or inline_markdown filter. If you use RichText, you must always use the {{r ... }} prefix.
{{r client_address | RichText }}
Source: Documents: multi-line or formatted text.
What does “TypeError: Argument ‘element’ has incorrect type (expected lxml.etree._Element, got NoneType)” mean?
Answer: This error comes up when Docassemble assembles a DOCX file. In the public Stack Overflow thread, the answers trace it to the DOCX file itself, not to the interview. One answer points to a bug in docxcompose, a library Docassemble depends on, triggered by very small errors in the file that Word fixes automatically when you save. Open the template in Microsoft Word and save it again. If that doesn’t work, build a fresh document with one field, test it, and add the rest back gradually.
Symptom: generating a document from a docx template file fails with the lxml TypeError above.
Fix: 1. Open the template in Microsoft Word and save it, which repairs minor structural errors. 2. If it still fails, create a new .docx, add a single field and test it. Then add the remaining content a section at a time until you find the part that breaks.
Source: Stack Overflow question 65633886 and the upstream docxcompose pull request #58 it links to. (Editor’s note: neither answer was marked accepted. Treat this as a known workaround, not a confirmed root cause.)
Why do ampersands break Jinja2 code in my template?
Answer: A GitHub issue reported that ampersands inside Jinja2 Python code were converted to &, which breaks the expression. The issue is now closed. If you see this on your version, keep & out of template expressions: compare and combine values in the interview’s YAML or Python code, then pass the result to the template.
Source: GitHub issue #233. (Editor’s note: the issue doesn’t say which version fixed it. Test on a current server before stating whether it still happens.)
How do you resize an image in a DOCX template?
Answer: Use the .show() method with a width parameter on the image variable, alone in its own tag: {{ user_picture.show(width="2in") }}. You don’t need python-docx-template’s replace_pic(). If the image is cropped, change the paragraph’s line spacing from a fixed value to “single” or “double”.
question: |
Please upload a picture of yourself.
fields:
- Picture: user_picture
datatype: file
{{ user_picture.show(width="2in") }}
The docs say: “To change the width of an image, use the .show() method with a width parameter”, and that fixed line spacing crops images taller than the line (Documents). The same answer is given in Stack Overflow question 70607184.
How do you debug a template that renders blank fields?
Answer: Blank fields usually mean the variable was never defined, its name in the template doesn’t match the interview, or skip undefined replaced it with a blank. Check names with the “Get list of fields from PDF/DOCX template” utility, map mismatches with fields, and use skip undefined only deliberately.
attachment:
name: Engagement letter
filename: engagement_letter
docx template file: engagement_letter.docx
fields:
client_name: ${ client.name.full() }
The docs warn that if a template contains computations, skip undefined: True “may lead to bugs” (Documents). Base your logic on substantive answers, not on whether a variable happens to be defined.
FAQ
Can I edit DOCX templates in Google Docs or LibreOffice? You can, but the safest tool for Jinja2 tags is Microsoft Word with autocorrect for “smart quotes” turned off. Whatever editor you use, retype any tag that fails rather than editing it piecemeal.
Should I use DOCX or PDF templates? Use DOCX when the document’s length and wording change based on answers. Use a fillable PDF when a court or agency requires its exact official form. See our PDF fill troubleshooting guide (link live once article 2 is published).
Can Docassemble output both DOCX and PDF from one template?
Yes. A docx template file can produce PDF or DOCX output; set valid formats to control which ones users can download.
How do I fix the lxml ‘Argument element has incorrect type’ error? Open the .docx template in Microsoft Word and save it again, which fixes small structural errors in the file. If the error persists, rebuild the template from a fresh document and add fields back gradually.
Why does my template work in the Playground but fail in production?
Usually a missing package, a template file outside data/templates, or a different Docassemble version. Check the server logs and confirm both servers run the same version.
Need a second pair of eyes?
If a template still won’t assemble, send us one broken file. Our free Docassemble audit reviews templates, interview logic and hosting, with a written fix list.
Related reading – Docassemble document templates: PDF and DOCX formatting that doesn’t break – Migrate Word templates to Docassemble: a step-by-step guide – Generate PDF and DOCX documents in Docassemble – Fix a broken Docassemble interview: common YAML and logic issues
Sources: docassemble.org — Documents, docassemble.org — Functions, GitHub jhpyle/docassemble issues #756, #805, #857, #946, #233; Stack Overflow 65633886, 70607184. Checked 1 Nov 2026.
More in this Docassemble troubleshooting series – Complete Docassemble troubleshooting guide – Docassemble PDF fill problems: fields, checkboxes and signatures – Docassemble Docker upgrade and deployment problems – Docassemble support and maintenance