---
title: "DOCX template merge errors"
description: "Fix DOCX template errors and merge surprises: template-error, cannot-populate-template, duplicated tables, missing fields and values in the wrong format."
canonical: "https://signatureapi.com/docs/troubleshooting/templates"
source: "https://signatureapi.com/docs/troubleshooting/templates.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:06:40Z"
---

# 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.

_Last verified against API version 1.18.0._

A [DOCX template](https://signatureapi.com/docs/api/resources/documents/templates) 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`](https://signatureapi.com/docs/v1/errors/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](https://signatureapi.com/docs/api/resources/documents/templates#try-a-merge) takes a template and its data and shows the merged text, without sending anything.

## template-error: the tags can't be read

[`template-error`](https://signatureapi.com/docs/v1/errors/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](https://signatureapi.com/docs/api/resources/documents/templates#repeating-regions).

## cannot-populate-template: the data doesn't fit

[`cannot-populate-template`](https://signatureapi.com/docs/v1/errors/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](https://signatureapi.com/docs/api/resources/documents/templates#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](https://signatureapi.com/docs/api/resources/places/positioning), 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](https://signatureapi.com/docs/troubleshooting/places).

## Related

- [Document templates](https://signatureapi.com/docs/api/resources/documents/templates): fields, conditionals and repeating regions.
- [Documents](https://signatureapi.com/docs/api/resources/documents/object): formats and limits.
- [Troubleshooting places](https://signatureapi.com/docs/troubleshooting/places): placeholders and positions.
