> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common notification template issues.

# 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:**

1. **Unbalanced brackets**

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

   ```handlebars theme={null}
   <!-- ❌ Missing closing /if -->
   {{#if entity.owner}}
     Owner: {{entity.owner}}

   <!-- ✅ Correct -->
   {{#if entity.owner}}
     Owner: {{entity.owner}}
   {{/if}}
   ```

2. **Incorrect helper syntax**

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

   ```handlebars theme={null}
   <!-- ❌ Misspelled helper -->
   {{formatDate entity.updatedAt}}

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

3. **Missing quotes in string attributes**

   * String values must be quoted.

   ```handlebars theme={null}
   <!-- ❌ 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.

<Warning>
  **Important**: Double-quote all string values in Handlebars attributes: `status='Failed'` is incorrect, use `status="Failed"` instead.
</Warning>

### 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:**

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

2. **Use the `limit` helper**
   ```handlebars theme={null}
   <!-- Show only first 10 changes instead of all -->
   {{#each (limit (filter changes.updates) 10)}}
     {{name}}
   {{/each}}
   ```

3. **Show summaries instead of details**
   ```handlebars theme={null}
   <!-- ❌ 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}}
   ```

4. **Remove conditional sections for optional data**
   ```handlebars theme={null}
   <!-- Only show tags if they exist -->
   {{#if (gt (length entity.tags) 0)}}
     Tags: {{#each (limit entity.tags 5)}}{{tagFQN}}, {{/each}}
   {{/if}}
   ```

5. **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:**

1. **Verify property names**
   * Check [Template Context Reference](/ai-2-0/how-to-guides/data-quality-observability/alerts-notifications/notification-templates/template-context-reference)
   * Use dot notation: `entity.owner`, not `entity.owner_name`

2. **Use conditionals for optional fields**
   ```handlebars theme={null}
   {{#if entity.owner}}
     Owner: {{entity.owner}}
   {{/if}}
   ```

3. **Check for property availability by entity type**
   ```handlebars theme={null}
   {{#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:**

1. **Validate HTML**

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

   ```html theme={null}
   <!-- ❌ 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>
   ```

2. **Use the Preview feature**
   * Preview shows how template renders with sample data.
   * Check preview across different channel types.

3. **Send test notifications**
   * Test to your actual Slack/email/Teams channels.
   * Verify formatting in each platform.

4. **Check special characters**

   * Characters like `<`, `>`, `&` need escaping in HTML.
   * Use `&lt;`, `&gt;`, `&amp;` instead.

   ```html theme={null}
   <!-- ❌ 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:**

1. **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.

2. **Check subscription is active**
   * Enable/activate the subscription.
   * Verify it's not disabled.

3. **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:**

1. **Use conditionals to handle missing data**
   ```handlebars theme={null}
   {{#if entity.owner}}
     <p>Owner: {{entity.owner}}</p>
   {{else}}
     <p><em>No owner assigned</em></p>
   {{/if}}
   ```

2. **Check property availability**
   ```handlebars theme={null}
   {{#if entity.description}}
     {{entity.description}}
   {{/if}}
   ```

3. **Verify nested properties exist**
   ```handlebars theme={null}
   {{#if entity.testCaseResult}}
     {{#if entity.testCaseResult.result}}
       Result: {{entity.testCaseResult.result}}
     {{/if}}
   {{/if}}
   ```

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

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

```handlebars theme={null}
<!-- ❌ 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:**

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

2. **Verify `baseUrl` is set**
   * The system should automatically set `baseUrl`.
   * Check if your Collate URL is configured correctly.

3. **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:**

1. **Misspelled helper name**
   ```handlebars theme={null}
   <!-- ❌ Typo in helper name -->
   {{len entity.tags}}

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

2. **Wrong number of arguments**
   ```handlebars theme={null}
   <!-- ❌ limit needs 2 arguments -->
   {{limit entity.tags}}

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

3. **Arguments in wrong order**
   ```handlebars theme={null}
   <!-- ❌ Wrong order -->
   {{split "." entity.fullyQualifiedName}}

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

**Solution:**

* Check [Custom Helpers Reference](/ai-2-0/how-to-guides/data-quality-observability/alerts-notifications/notification-templates/custom-helpers-reference)
* Verify exact helper name and argument order.
* Use Preview to test.

## Best Debugging Practices

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

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

```handlebars theme={null}
<!-- 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.