Troubleshooting

When a generated document is blank, incomplete, or missing values, the cause is almost always in the template itself — a misspelled field name, incorrect section syntax, or a missing data-sheet entry. This page covers the most common issues and how to diagnose them.

All placeholder names in a template come from the machine names defined on the entity type the template is attached to. Most troubleshooting starts with comparing what the template says against what the entity type defines.

Blank values where data should appear

Symptom: A generated document has empty spaces where field values were expected.

Likely causes:

Misspelled field name

The placeholder {{custmerName}} does not match the field’s machine name customerName (defined on the entity type). Unrecognized placeholders resolve to empty strings — no error is shown.

Fix: Compare the placeholder name in the template with the machine name in the entity type definition under Settings → Entities. Machine names are case-sensitive.

Wrong context

Inside a repeating section, placeholders resolve against the current item — the nested entity type — not the top-level record. A placeholder like {{dealNumber}} inside a {{#items}} section looks for a field with machine name dealNumber on the line item entity type, not on the deal entity type.

Fix: Use {{$.dealNumber}} to reach the root context, or {{../dealNumber}} to reach the parent context. See accessing outer fields for details.

Field has no value

The field exists on the entity type but the specific record has no value stored for it.

Fix: Open the record in the interface and verify that the field has a value.

Entire document is blank

Symptom: The generated file contains the template’s static text and layout, but every placeholder resolved to empty.

Likely causes:

Template attached to the wrong entity type

If the template is attached to entity type A but the machine names in its placeholders belong to entity type B, none of the placeholders match.

Fix: Verify that the template is attached to the correct entity type in the administration section.

No data in the record

The record exists but has no field values filled in.

Fix: Open the record and verify that its fields contain data.

Repeating section produces no rows

Symptom: A table or slide section that should repeat for each item produces no output — the rows or slides are missing entirely.

Likely causes:

Collection name mismatch

The section tag {{#lineItems}} does not match the collection field’s machine name in the data, which might be items. The name inside the # tag must be the exact machine name of the collection field (a nested entity or link-to-many) on the entity type.

Fix: Open the entity type definition and check the collection field’s machine name. For proposals, the standard collection key is typically items.

Empty collection

The collection exists but contains no items. When a collection is empty, the repeating section is removed entirely — this is correct behavior, not an error.

Fix: Add items to the collection (for example, add line items to the proposal).

Incorrect tag placement (DOCX tables)

In a three-row table pattern, the opening and closing tag rows must be separate rows. In a single-row pattern, the opening tag must be in the first cell and the closing tag in the last cell.

Fix: Review the tag placement according to the patterns described in repeating sections.

Image placeholder shows text instead of an image

Symptom: The output shows the placeholder text (or a raw value) in the shape instead of an image.

Likely causes:

Mixed content in the shape

The shape contains other text besides the placeholder tag. Image replacement requires the placeholder to be the entire content of the shape.

Fix: Remove all text from the shape except the placeholder tag itself.

Field is not an image reference

The field value is a text string. The engine inserts a text string as ordinary text.

Fix: Verify that the field on the entity type is of type File or Image (see data types).

Unsupported image format

The image file is in a format the engine does not recognize.

Fix: Convert the image to one of the supported formats listed in image placeholders.

XLSX error markers

XLSX templates have built-in error resilience. If a single cell fails to render, the cell contains ERR: followed by the error type and message. If an entire sheet fails, cell A1 of that sheet contains RENDER ERROR followed by the sheet name and error detail. In both cases the rest of the workbook renders normally.

See error resilience in the Excel templates page for details.

_data sheet values are missing (XLSX)

Symptom: Collections loaded through the _data sheet produce no data on the output sheets.

Likely causes:

Check for an _errors sheet

Open the generated workbook and look for a sheet named _errors. If it exists, it lists each data source that failed to load, the entity type it tried to query, the filter expression, and the error message.

Entity type machine name is wrong

The value in column B of the _data sheet does not match any entity type machine name in the organization.

Fix: Verify the machine name against the entity type definition in Settings → Entities.

Filter expression is invalid

The expression in column C has a syntax error or references a field machine name that does not exist on the target entity type.

Fix: Simplify the filter or remove it temporarily to verify that the data source loads without it. See the _data sheet for filter expression syntax.

Permission denied

The user generating the document does not have read permission on the entity type.

Fix: Check the user’s role permissions for the entity type in question.

Reserved collection key

The collection key (column A) uses a reserved name — items or filter. Rows with reserved keys are skipped.

Fix: Rename the collection key to something else.

Expression placeholder returns empty

Symptom: An expression placeholder {{=...}} produces no output.

Likely causes:

Syntax error

The JavaScript expression has a syntax error — for example, an unclosed parenthesis or an undefined function.

Fix: Review the expression syntax. Test simple expressions first and build up complexity.

Undefined variable

The expression references a field machine name that does not exist in the current context.

Fix: Verify the field machine name on the entity type and check whether the expression is inside a repeating section (where the context is the current item’s entity type, not the root record). See expressions and formatting for syntax details.

Expression runs too long

An expression that runs too long is stopped. This is unlikely with simple arithmetic but can happen with very complex logic.

Fix: Simplify the expression.

DOCX debug placeholder

In DOCX templates, the special placeholder {{debug}} returns a complete dump of all data available to the template, formatted as JSON. This is useful for inspecting:

  • which fields are available and what their machine names are,

  • what values the record contains,

  • the structure of collections (which fields each nested item has — see nested entities).

To use it, add {{debug}} to a paragraph in the template, generate the document, and inspect the output. Remove the placeholder before publishing the template for production use.

The {{debug}} placeholder is available only in DOCX templates.

Checklist

When a generated document has issues, work through this checklist:

  1. Open the entity type definition and note the exact machine names of the fields.

  2. Open the record and verify that the relevant fields have values.

  3. Open the template file and compare each placeholder against the machine names — check spelling and case.

  4. For repeating sections, verify the collection key name and the tag placement pattern.

  5. For expression placeholders, verify the JavaScript syntax and the field names used in the expression.

  6. For image placeholders, verify that the shape contains only the placeholder tag and that the field holds an image reference.

  7. For _data sheet issues, check the generated workbook for an _errors sheet.

  8. For DOCX templates, use the {{debug}} placeholder to inspect the available data.

Related pages