Troubleshooting
DOCX template merge errors
Fix DOCX template errors and merge surprises: template-error, cannot-populate-template, duplicated tables, missing fields and values in the wrong format.
A DOCX template fails in one of two places. SignatureAPI can’t read the template’s tags, or it reads them but can’t fill them from your data. Both fail the create request with a 422, so no envelope is created. Then there are merges that succeed but don’t look the way you expected.
Before you start
- Set
formattodocx. A DOCX sent without it, or with"format": "pdf", fails withcannot-parse-document. - Read the
detail. It says what went wrong. Forcannot-populate-template, it also names the document by its position, such asdocuments[0]. - Try the merge in the browser. The merge preview takes a template and its data and shows the merged text, without sending anything.
template-error: the tags can’t be read
template-error means the template’s syntax is broken. Look for:
- Unbalanced braces. Every
{{needs a matching}}. A single{or}next to a tag also confuses the parser. - Unclosed blocks. Every
{{if ...}}needs its{{endif}}, and every range tag such as{{#data.events}}needs its{{/data.events}}. - Literal braces in the text. Any
{{...}}in the document is treated as a tag, even in an example or a footnote. To mention a field in the text, write it without braces. - Mixed repeating patterns. A document uses either the simple repeating pattern or the root wrapper with range tags, not both. See Repeating regions.
cannot-populate-template: the data doesn’t fit
cannot-populate-template means the tags are fine but your data doesn’t match them. Check:
- Missing keys. Every field in the template needs a value in
data. For a repeating region, every item in the array needs every field used inside the region. - Key spelling and case. Field names are case sensitive:
{{client.Name}}and{{client.name}}are different fields. - Nesting.
{{client.name}}reads{ "client": { "name": "..." } }, an object insidedata, not a key calledclient.name.
The merge works but looks wrong
A table repeats header and all
Range tags placed in paragraphs above and below a table duplicate the whole table once per item. Put {{#data.<arrayName>}} at the start of the first cell of the data row and {{/data.<arrayName>}} at the end of its last cell. Only that row repeats. See Several repeating regions in one document.
Regions multiply or text moves between them
With more than one array in a document, or the same array used twice, the simple pattern can’t tell where each region ends. Split the content into separate documents in the same envelope, each with its own template and data, or use the root wrapper with range tags.
Dates and amounts aren’t formatted
SignatureAPI inserts each value exactly as you send it. Format dates, amounts and other numbers in your code first, such as "December 31, 2025" or "$1,250.00", and send them as strings.
A signature place is missing or repeated
[[place_key]] placeholders position places, and they don’t belong inside a repeating region: every copy of the region would compete for the same place. Keep placeholders outside repeating regions. If a place isn’t found at all, see Placeholders not detected.
Related
- Document templates: fields, conditionals and repeating regions.
- Documents: formats and limits.
- Troubleshooting places: placeholders and positions.