Troubleshooting

This guide helps you resolve common issues with notification templates.

Template Validation Errors

These errors appear when saving a template that contains invalid syntax or exceeds size limits.

Syntax Error: Invalid Handlebars Syntax

Error Message: “Invalid Handlebars syntax” or “Unexpected token” Common Causes:

Unbalanced brackets

Every {{#if}} needs a closing {{/if}}
Every {{#each}} needs a closing {{/each}}

<!-- ❌ Missing closing /if -->
{{#if entity.owners}}
  Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}

<!-- ✅ Correct -->
{{#if entity.owners}}
  Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}
{{/if}}

Incorrect helper syntax

Verify helper names are spelled correctly.
Check that parentheses are balanced.

<!-- ❌ Misspelled helper -->
{{formatDate entity.updatedAt}}

<!-- ✅ Correct -->
{{formatDate entity.updatedAt}}

Missing quotes in string attributes

String values must be quoted.

<!-- ❌ Missing quotes -->
{{#if (eq status Failed)}}

<!-- ✅ Correct -->
{{#if (eq status "Failed")}}

Solution:

Use the Validate button in the template editor before saving.
Check brackets are balanced: each opening has a closing pair.
Verify helper names match exactly (case-sensitive).
Add quotes around string values in helper attributes.

Important: Double-quote all string values in Handlebars attributes: status='Failed' is incorrect, use status="Failed" instead.

Max Length Error: Template Exceeds 65,536 Characters

Error Message: “Template body exceeds maximum length” Common Causes:

Template is too comprehensive.
Too many examples or detailed change descriptions.
Large data structures being displayed without filtering.

Solutions:

Simplify the template
- Remove unnecessary formatting.
- Remove comments.
- Use shorter variable names where possible.

Use the limit helper In the examples below, changes comes from {{#with (groupEventChanges event.changeDescription) as |changes|}}.

<!-- Show only first 10 changes instead of all -->
{{#each (limit (filter changes.updates) 10)}}
  {{name}}
{{/each}}

Show summaries instead of details

<!-- ❌ Shows all field details (verbose) -->
{{#each changes.updates}}
  {{name}}: {{oldValue}} → {{newValue}}
{{/each}}

<!-- ✅ Shows only count and highlights (concise) -->
{{length changes.updates}} fields updated
{{#if entity.owners}}(Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}){{/if}}

Remove conditional sections for optional data

<!-- Only show tags if they exist -->
{{#if (gt (length entity.tags) 0)}}
  Tags: {{#each (limit entity.tags 5)}}{{tagFQN}}, {{/each}}
{{/if}}

Split into multiple templates
- Create separate templates for detailed vs. summary views.
- Use different templates for different entity types.

Field Name Not Recognized

Error Message: Template doesn’t render field, shows empty string Common Causes:

Incorrect property path.
Property doesn’t exist for this entity type.
Typo in property name.

Solution:

Verify property names
- Check Template Context Reference
- Use dot notation: entity.owners.0.name, not entity.owner_name

Use conditionals for optional fields

{{#if entity.owners}}
  Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}
{{/if}}

Check for property availability by entity type

{{#if (eq event.entityType "testCase")}}
  Status: {{entity.testCaseStatus}}
{{/if}}

{{#if (eq event.entityType "table")}}
  Columns: {{length entity.columns}}
{{/if}}

Notifications Not Rendering Correctly

These issues occur when a template is saved successfully but produces garbled or missing output in delivered notifications.

Notifications Look Garbled or Misformatted

Symptoms:

Text appears without line breaks.
HTML tags visible in notification.
Formatting looks different on different channels.

Common Causes:

HTML is malformed.
Characters aren’t escaped properly.
Channel-specific formatting issues.

Solutions:

Validate HTML

Ensure all HTML tags are properly closed.
Use standard HTML tags (not XHTML self-closing unless valid).

<!-- ❌ Unclosed tags -->
<p>This is a paragraph
<ul><li>Item 1</ul>

<!-- ✅ Properly closed -->
<p>This is a paragraph</p>
<ul><li>Item 1</li></ul>

Validate the template
- Click Validate in the template editor to check the syntax.
Send test notifications
- Test to your actual Slack/email/Teams channels.
- Verify formatting in each platform.

Check special characters

Characters like <, >, & need escaping in HTML.
Use <, >, & instead.

<!-- ❌ This will break HTML -->
<p>{{entity.description}} contains < and > characters</p>

<!-- ✅ Use proper escaping -->
<p>{{{entity.description}}} (use triple braces for HTML content)</p>

Template Selected But Not Showing

Symptoms:

Notifications are sent but template isn’t being used.
Using default formatting instead of custom template.

Causes:

Template not selected in subscription.
Subscription is inactive.
Event type doesn’t match what subscription is listening for.

Solutions:

Verify template is selected
- Go to Settings > Notifications > Subscriptions.
- Edit the subscription.
- Confirm the Notification Template dropdown has your template selected and is not blank.
Check subscription is active
- Enable/activate the subscription.
- Verify it’s not disabled.
Verify event types match
- Subscription must be listening to entity updates that match your template.
- Example: Template for tables won’t be used for dashboard updates.

Missing Data in Notifications

These issues occur when a template renders successfully but displays blank values or empty sections.

Template Shows Empty Values

Symptoms:

Owner: appears with no value.
Sections are blank even though field should exist.
Links or data don’t appear.

Common Causes:

Data doesn’t exist for this entity instance.
Property name is different than expected.
Data is nested differently.

Solutions:

Use conditionals to handle missing data

{{#if entity.owners}}
  <p>Owner: {{#each entity.owners}}{{name}}{{#unless @last}}, {{/unless}}{{/each}}</p>
{{else}}
  <p><em>No owner assigned</em></p>
{{/if}}

Check property availability

{{#if entity.description}}
  {{entity.description}}
{{/if}}

Verify nested properties exist

{{#if entity.testCaseResult}}
  {{#if entity.testCaseResult.result}}
    Result: {{entity.testCaseResult.result}}
  {{/if}}
{{/if}}

Note: If a field is missing, the template renders an empty string. Always use conditional logic to prevent empty sections.

Change Data Not Displaying Correctly

Symptoms:

Updated fields showing as empty.
Can’t see what changed in the notification.

Causes:

Not using groupEventChanges helper.
Trying to access raw change description.

Solution: Always use groupEventChanges to organize change data:

<!-- ❌ Don't access changeDescription directly -->
{{event.changeDescription}}

<!-- ✅ Use groupEventChanges helper -->
{{#with (groupEventChanges event.changeDescription) as |changes|}}
  {{#if changes.updates}}
    <h3>Updated:</h3>
    {{#each changes.updates}}
      {{name}}: {{oldValue}} → {{newValue}}
    {{/each}}
  {{/if}}
{{/with}}

Link and URL Issues

These issues occur when notification links return 404 errors or navigate to the wrong entity.

Links Don’t Work or Point to Wrong Place

Symptoms:

Clicking link in notification shows 404 error.
Link goes to wrong entity.

Causes:

Incorrect entity type in URL.
baseUrl is not configured.
Entity IDs have changed.

Solutions:

Use buildEntityUrl helper

<!-- ✅ Best practice: Use helper -->
<a href="{{buildEntityUrl event.entityType entity}}">
  View {{entity.displayName}}
</a>

Verify baseUrl is set
- The system should automatically set baseUrl.
- Check if your Collate URL is configured correctly.
Test links
- Send test notifications.
- Click links and verify they work.

Helper Issues

These issues occur when a helper is called incorrectly or produces unexpected output.

Helper Not Found or Returns Wrong Result

Symptoms:

“Helper not found” error.
Helper name is red/underlined in editor.
Results are unexpected.

Common Issues:

Misspelled helper name

<!-- ❌ Typo in helper name -->
{{len entity.tags}}

<!-- ✅ Correct -->
{{length entity.tags}}

Wrong number of arguments

<!-- ❌ limit needs 2 arguments -->
{{limit entity.tags}}

<!-- ✅ Correct: array and max count -->
{{limit entity.tags 5}}

Arguments in wrong order

<!-- ❌ Wrong order -->
{{split "." entity.fullyQualifiedName}}

<!-- ✅ Correct: string first, then delimiter -->
{{split entity.fullyQualifiedName "."}}

Solution:

Check Custom Helpers Reference
Verify exact helper name and argument order.
Click Test Template in the alert form to test.

Best Debugging Practices

Follow these practices to diagnose template issues quickly and avoid common mistakes.

1. Validate Frequently

In the template editor, click Validate to catch syntax errors early. Validation doesn’t check whether a placeholder exists.

2. Send Test Notifications

In the alert form, click Test Template to:

Send to real email/Slack/Teams.
Verify how it actually appears to users.
Test with your actual notification setup.

3. Start Simple

When building templates:

Start with basic template.
Add features one at a time.
Test each addition.

<!-- Start here -->
{{entity.displayName}} was updated

<!-- Then add details -->
{{entity.displayName}} was updated
{{#with (groupEventChanges event.changeDescription) as |changes|}}
  Updated: {{#each changes.updates}}{{name}}{{/each}}
{{/with}}

<!-- Then add formatting and styling -->
<!-- ... etc -->

4. Ask for Help

Provide:

The template code.
What error or unexpected behavior occurs.
What data you expected to see.
Screenshots of the validation or test results.

​Troubleshooting

​Template Validation Errors

​Syntax Error: Invalid Handlebars Syntax

​Max Length Error: Template Exceeds 65,536 Characters

​Field Name Not Recognized

​Notifications Not Rendering Correctly

​Notifications Look Garbled or Misformatted

​Template Selected But Not Showing

​Missing Data in Notifications

​Template Shows Empty Values

​Change Data Not Displaying Correctly

​Link and URL Issues

​Links Don’t Work or Point to Wrong Place

​Helper Issues

​Helper Not Found or Returns Wrong Result

​Best Debugging Practices

​1. Validate Frequently

​2. Send Test Notifications

​3. Start Simple

​4. Ask for Help

Troubleshooting

Template Validation Errors

Syntax Error: Invalid Handlebars Syntax

Max Length Error: Template Exceeds 65,536 Characters

Field Name Not Recognized

Notifications Not Rendering Correctly

Notifications Look Garbled or Misformatted

Template Selected But Not Showing

Missing Data in Notifications

Template Shows Empty Values

Change Data Not Displaying Correctly

Link and URL Issues

Links Don’t Work or Point to Wrong Place

Helper Issues

Helper Not Found or Returns Wrong Result

Best Debugging Practices

1. Validate Frequently

2. Send Test Notifications

3. Start Simple

4. Ask for Help