Troubleshooting

This guide helps you resolve common issues with notification templates.

Template Validation Errors

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.owner}}
  Owner: {{entity.owner}}

<!-- ✅ Correct -->
{{#if entity.owner}}
  Owner: {{entity.owner}}
{{/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

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

Max Length Error: Template Exceeds 10,240 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

<!-- 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.owner}}(Owner: {{entity.owner}}){{/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.owner, not entity.owner_name

Use conditionals for optional fields

{{#if entity.owner}}
  Owner: {{entity.owner}}
{{/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

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>

Use the Preview feature
- Preview shows how template renders with sample data
- Check preview across different channel types
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
- Not just 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

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.owner}}
  <p>Owner: {{entity.owner}}</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}}

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

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

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
Use Preview to test

Best Debugging Practices

1. Use Preview Frequently

In the template editor, click Preview to:

See how template renders with sample data
Catch formatting issues early
Test across different channels

2. Send Test Notifications

Click Send Test 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 Preview/test results

Overview

Data Quality & Observability

Troubleshooting

Troubleshooting

Template Validation Errors

Syntax Error: Invalid Handlebars Syntax

Max Length Error: Template Exceeds 10,240 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. Use Preview Frequently

2. Send Test Notifications

3. Start Simple

4. Ask for Help

Overview

Data Quality & Observability

​Troubleshooting

​Template Validation Errors

​Syntax Error: Invalid Handlebars Syntax

​Max Length Error: Template Exceeds 10,240 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. Use Preview 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 10,240 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. Use Preview Frequently

2. Send Test Notifications

3. Start Simple

4. Ask for Help