Skip to content

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 format to docx. A DOCX sent without it, or with "format": "pdf", fails with cannot-parse-document.
  • Read the detail. It says what went wrong. For cannot-populate-template, it also names the document by its position, such as documents[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 inside data, not a key called client.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.