Template Errors

Bengal provides rich error messages for template issues. This guide helps you understand and resolve common template errors.

Understanding Template Errors

When Bengal encounters a template error, it displays:

• Error type - What kind of error (syntax, undefined variable, unknown filter)
• Location - File path and line number
• Code context - Surrounding lines with the error highlighted
• Suggestions - Potential fixes based on the error type
• Search paths - All directories Bengal checked for templates

Enabling Proactive Validation

Catch template errors early by enabling validation in your config:

[build]
validate_templates = true

This validates all templates during build, even those not used by every page. Combine with strict_mode = truefor CI/CD pipelines.

Common Error Types

Syntax Errors

Symptoms:

• unexpected '}'
• expected token 'end of statement block'
• Unexpected end of template

Causes:

• Unclosed tags ({% if ... %} without {% end %} or {% endif %})
• Missing closing brackets
• Invalid template syntax

Example: Error Message

⚠️  Template Syntax Error in partials/nav.html:15

    14 | {% for item in menu.items %}
  > 15 |   <li>{{ item.name }
    16 | {% endfor %}

Error: unexpected end of template, expected 'end of print statement'

Fix: Add the missing }}:

<li>{{ item.name }}</li>

Undefined Variables

Symptoms:

• 'variable_name' is undefined
• 'dict object' has no attribute 'key'

Causes:

• Typo in variable name
• Variable not passed to template context
• Accessing dict key that doesn't exist

Example: Error Message

⚠️  Undefined Variable in page.html:8

Error: 'titel' is undefined

💡 Suggestions:
   1. Common typo: try 'title' instead
   2. Use safe access: {{ titel | default('fallback') }}
   3. Add 'titel' to page frontmatter

Fix options:

1. Correct the typo:Template Errors instead of {{ titel }}
2. Use thedefault filter: {{ variable | default('fallback') }}
3. Use safe dot-notation: `` (returns empty string if missing)

Unknown Filters

Symptoms:

• No filter named 'filter_name'

Causes:

• Typo in filter name
• Using a filter from another SSG (Hugo, Jekyll, etc.)
• Custom filter not registered

Example: Error Message

⚠️  Unknown Filter in page.html:12

Error: No filter named 'in_section'

💡 Suggestions:
   1. Bengal doesn't have 'in_section' filter.
      Check if the page is in a section using: {% if page.parent %}

Did you mean:
   • first
   • list

Common filter migrations:

Template Not Found

Symptoms:

• TemplateNotFound: template_name.html

Causes:

• Typo in template name
• Template in wrong directory
• Theme not installed or misconfigured

Example: Error Message

⚠️  Template Error

Error: TemplateNotFound: partials/sidebar.html

🔍 Template Search Paths:
   1. /site/templates
   2. /site/themes/custom/templates
   3. /bengal/themes/default/templates

Diagnosis:

1. Check the search paths listed in the error
2. Verify the template exists in one of those directories
3. Check for case sensitivity issues
4. Ensure theme is correctly configured

Fix:

• Create the missing template intemplates/ or themes/your-theme/templates/
• Fix the template name in your code
• Check theme configuration inbengal.toml

Template Search Path Order

Bengal searches for templates in this order:

1. Site templates -your-site/templates/
2. Theme templates -your-site/themes/theme-name/templates/
3. Installed themes - Via Python entry points
4. Bundled themes - Bengal's built-in themes
5. Default theme - Ultimate fallback

Templates in higher-priority directories override lower ones.

Best Practices

Use Safe Access for Optional Data

Bengal templates useChainableUndefined, which means missing values return empty strings instead of errors:

{# Direct access - returns empty string if missing #}
{{ params.custom_field }}

{# With explicit default #}
{{ params.custom_field | default('fallback') }}

{# Cascading params (page → section → site) #}
{{ params.author }}  {# Checks page, then section, then site params #}

Check Variables Before Use

{% if params.author %}
  <p>By {{ params.author }}</p>
{% end %}

Enable Validation in Development

# bengal.toml
[build]
validate_templates = true

Enable Strict Mode in CI

# config/environments/production.yaml
build:
  validate_templates: true
  strict_mode: true

Or via CLI:

bengal build --validate --strict

Getting Help

If you're stuck:

1. Check the full error message - Bengal provides detailed context
2. Review template search paths - Ensure templates are in the right location
3. Use verbose mode - Runbengal build --verbosefor more output
4. Use developer profile - Runbengal build --devfor full debug output
5. Check the template documentation - See Template Functions