# Template Errors URL: /docs/building/troubleshooting/template-errors/ Section: troubleshooting -------------------------------------------------------------------------------- Template Error Troubleshooting 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: 1 2[build] validate_templates = true This validates all templates during build, even those not used by every page. Combine with strict_mode = true for 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 {% endif %}) Missing closing brackets Invalid Jinja2 syntax Example error: ⚠️ 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: ⚠️ 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: Correct the typo: {{ title }} instead of {{ titel }} Use safe access: {{ page.metadata.get('custom_field', 'default') }} Use the default filter: {{ variable | default('fallback') }} 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: ⚠️ 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: • intersection • int Common filter migrations: From Hugo/Jekyll Bengal Equivalent markdownify markdown truncatewords truncate with word mode in_section {% if page.parent %} is_ancestor Compare page.url values Template Not Found Symptoms: TemplateNotFound: template_name.html Causes: Typo in template name Template in wrong directory Theme not installed or misconfigured Example error: ⚠️ Template Error Error: TemplateNotFound: partials/sidebar.html 🔍 Template Search Paths: 1. /site/templates 2. /site/themes/custom/templates 3. /bengal/themes/default/templates Diagnosis: Check the search paths listed in the error Verify the template exists in one of those directories Check for case sensitivity issues Ensure theme is correctly configured Fix: Create the missing template in templates/ or themes/your-theme/templates/ Fix the template name in your code Check theme configuration in bengal.toml Template Search Path Order Bengal searches for templates in this order: Site templates - your-site/templates/ Theme templates - your-site/themes/theme-name/templates/ Installed themes - Via Python entry points Bundled themes - Bengal's built-in themes Default theme - Ultimate fallback Templates in higher-priority directories override lower ones. Best Practices Use Safe Access for Optional Data 1 2 3 4 5{# Safe access for metadata that might not exist #} {{ page.metadata.get('custom_field', 'default_value') }} {# Or use the default filter #} {{ page.custom_field | default('fallback') }} Check Variables Before Use 1 2 3{% if page.metadata.author %} <p>By {{ page.metadata.author }}</p> {% endif %} Enable Validation in Development 1 2 3 4# bengal.toml [build] validate_templates = true debug = true Enable Strict Mode in CI 1 2 3 4# config/environments/ci.yaml build: validate_templates: true strict_mode: true Getting Help If you're stuck: Check the full error message - Bengal provides detailed context Review template search paths - Ensure templates are in the right location Enable debug mode - Set debug = true for more verbose output Check the template documentation - See Template Functions -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 641 - Reading Time: 3 minutes