Troubleshooting¶

Common issues and solutions when working with Django IncludeContents.

Template Errors¶

TemplateDoesNotExist¶

Error:

TemplateDoesNotExist: components/my-component.html

Causes and Solutions:

Component file doesn't exist:
```
# Check if the file exists
ls templates/components/my-component.html
```
Solution: Create the component file in the correct location.

Incorrect file path:

<!-- ❌ Wrong -->
<include:my_component>

<!-- ✅ Correct -->
<include:my-component>

Solution: Use kebab-case and ensure the filename matches.

Missing components directory:

# Create the directory
mkdir -p templates/components

Template engine not configured:

# settings.py - Ensure you have the right backend
TEMPLATES = [{
    'BACKEND': 'includecontents.django.Engine',  # For HTML syntax
    # OR
    'BACKEND': 'django.template.backends.django.DjangoTemplates',  # For template tags
}]

TemplateSyntaxError¶

Error:

TemplateSyntaxError: Invalid block tag: 'includecontents'

Solution: Load the template tag library:

{% load includecontents %}
{% includecontents "components/card.html" %}
    Content
{% endincludecontents %}

Error:

TemplateSyntaxError: Malformed template tag at token 'includecontents'

Common causes:

Missing template name:

<!-- ❌ Wrong -->
{% includecontents %}
    Content
{% endincludecontents %}

<!-- ✅ Correct -->
{% includecontents "components/card.html" %}
    Content
{% endincludecontents %}

Incorrect attribute syntax:

<!-- ❌ Wrong -->
<include:card title=Hello World>

<!-- ✅ Correct -->
<include:card title="Hello World">

Enhanced Error Messages¶

Django IncludeContents provides enhanced error messages to help you quickly identify and fix issues:

Props Definition Errors¶

Enhanced props error messages include: - Exact line number where the error occurs - Specific problematic token - Common issues and solutions - Concrete examples of correct syntax

Example error:

Props parsing error: Invalid prop name 'invalid name'. Prop names must be valid Python identifiers.
  In template line 2: {# props "invalid name"=value #}
  Problem with: 'invalid name=value'

Common issues:
  - Prop names must be valid Python identifiers (no spaces, special chars)
  - String values should be quoted: name="value"
  - Lists should use brackets: items=[1,2,3]
  - Use commas or spaces to separate props: prop1=value1 prop2=value2

Examples:
  {# props title required_field=True items=[1,2,3] #}
  {# props variant=primary,secondary,accent size="large" #}

Common props definition errors:

Invalid prop names with spaces:

<!-- ❌ Wrong -->
{# props "user name"=default_value #}

<!-- ✅ Correct -->
{# props user_name=default_value #}

Invalid prop names with special characters:

<!-- ❌ Wrong -->
{# props prop-name=value #}

<!-- ✅ Correct -->
{# props prop_name=value #}

Malformed list syntax:

<!-- ❌ Wrong -->
{# props items=[1,2,3 #}

<!-- ✅ Correct -->
{# props items=[1,2,3] #}

Unquoted string values with spaces:

<!-- ❌ Wrong -->
{# props title=hello world #}

<!-- ✅ Correct -->
{# props title="hello world" #}

Enum Validation Errors¶

Enhanced enum error messages with suggestions:

Example error:

Invalid value "primari" for attribute "variant".
Allowed values: 'primary', 'secondary', 'accent'. Did you mean 'primary'?
Example: <include:button variant="primary">

Common enum errors:

Typos in enum values:

<!-- ❌ Wrong -->
<include:button variant="primari">  <!-- typo -->

<!-- ✅ Correct -->
<include:button variant="primary">

Case sensitivity issues:

<!-- ❌ Wrong -->
<include:button variant="PRIMARY">  <!-- wrong case -->

<!-- ✅ Correct -->
<include:button variant="primary">

Using underscores instead of hyphens:

<!-- ❌ Wrong -->
<include:button variant="dark_mode">  <!-- underscore -->

<!-- ✅ Correct -->
<include:button variant="dark-mode">  <!-- hyphen -->

Missing Template Errors¶

Enhanced template not found errors include: - Clear component identification - Specific template paths searched - Actionable suggestions for fixing

Example error:

Component template not found: <include:my-component>
Looked for: components/my-component.html

Suggestions:
  1. Create template: templates/components/my-component.html
  2. Check TEMPLATES['DIRS'] setting includes your template directory
  3. For app-based components: create template in <app>/templates/components/

Component Issues¶

Empty Component Content¶

Problem: Component renders but shows no content.

Debug steps:

Check props are being passed:

<!-- Debug template: templates/components/debug-card.html -->
{# props title, content="" #}
<div>
    <p>Title: "{{ title }}"</p>
    <p>Content: "{{ content }}"</p>
    <p>Contents: "{{ contents }}"</p>
</div>

Verify context isolation:

<!-- Parent template -->
{% with message="Hello" %}
    <!-- ❌ Wrong: message not passed -->
    <include:greeting>Welcome</include:greeting>

    <!-- ✅ Correct: message passed explicitly -->
    <include:greeting message="{{ message }}">Welcome</include:greeting>
{% endwith %}

Check for typos in variable names:

<!-- ❌ Wrong -->
<include:card titel="Hello">  <!-- typo: titel -->

<!-- ✅ Correct -->
<include:card title="Hello">

Missing Required Attributes¶

Error:

TemplateSyntaxError: Missing required attribute "title" in <include:card>

Solution: Provide all required attributes:

<!-- Component definition -->
{# props title, description="" #}

<!-- ❌ Wrong: missing required title -->
<include:card description="A card">Content</include:card>

<!-- ✅ Correct: title provided -->
<include:card title="My Card" description="A card">Content</include:card>

Variable Not Found in Component¶

Problem: Variables show as empty in component templates.

Debugging:

Check context isolation:

<!-- Parent template -->
<h1>{{ page_title }}</h1>  <!-- Works in parent -->

<include:card>
    <h2>{{ page_title }}</h2>  <!-- Empty in component! -->
</include:card>

Solution - pass variables explicitly:

<include:card page-title="{{ page_title }}">
    <h2>{{ page_title }}</h2>  <!-- Still empty -->
    <h2>{{ page-title }}</h2>  <!-- Works! -->
</include:card>

HTML Syntax Issues¶

HTML Components Not Working¶

Problem: HTML component syntax doesn't work, shows as literal text.

Check your template engine:

# settings.py
TEMPLATES = [{
    'BACKEND': 'includecontents.django.Engine',  # Required for HTML syntax
    'DIRS': [BASE_DIR / 'templates'],
    'APP_DIRS': True,
    # ...
}]

Common issues:

Wrong template engine:

# ❌ Won't work for HTML syntax
'BACKEND': 'django.template.backends.django.DjangoTemplates'

# ✅ Required for HTML syntax
'BACKEND': 'includecontents.django.Engine'

File not in components directory:

templates/
├── my-card.html          # ❌ Won't work
└── components/
    └── my-card.html      # ✅ Works

Self-Closing Tags Not Working¶

Problem:

<include:icon name="star" />  <!-- Doesn't work -->

Solution: Ensure proper self-closing syntax:

<!-- ✅ Correct -->
<include:icon name="star" />

<!-- ❌ Wrong - missing space before / -->
<include:icon name="star"/>

Performance Issues¶

Slow Template Rendering¶

Problem: Templates render slowly with many components.

Solutions:

Enable template caching:

# settings.py
TEMPLATES = [{
    'BACKEND': 'includecontents.django.Engine',
    'OPTIONS': {
        'loaders': [
            ('django.template.loaders.cached.Loader', [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            ]),
        ],
    },
}]

Avoid heavy computation in components:

<!-- ❌ Slow: complex calculations in template -->
{# props user #}
{% for post in user.posts.all %}
    {% for comment in post.comments.select_related.all %}
        <!-- Complex nested queries -->
    {% endfor %}
{% endfor %}

<!-- ✅ Fast: pass computed data -->
{# props user, user_stats #}
<div>Posts: {{ user_stats.post_count }}</div>
<div>Comments: {{ user_stats.comment_count }}</div>

Use conditional rendering:

{# props user, load_heavy_content=False #}
<div class="user-profile">
    <h1>{{ user.name }}</h1>

    {% if load_heavy_content %}
        <include:user-activity-feed user="{{ user }}" />
    {% endif %}
</div>

Development Issues¶

Component Changes Not Reflected¶

Problem: Component template changes don't appear in browser.

Solutions:

Disable template caching during development:

# settings.py (development only)
if DEBUG:
    TEMPLATES[0]['OPTIONS']['loaders'] = [
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    ]

Clear template cache:

# Restart development server
python manage.py runserver

# Or clear cache programmatically
python manage.py shell
>>> from django.template.loader import get_template
>>> get_template.cache_clear()

Check file paths:

# Ensure you're editing the right file
find . -name "my-component.html" -type f

IDE Not Recognizing Components¶

Problem: No syntax highlighting or autocomplete for components.

Solutions:

VS Code setup:

// .vscode/settings.json
{
    "emmet.includeLanguages": {
        "django-html": "html"
    },
    "files.associations": {
        "*.html": "django-html"
    }
}

Configure file associations:
Associate .html files with Django HTML language mode
Install Django extensions for your IDE

Error Debugging¶

Enable Debug Mode¶

Template debugging:

# settings.py
DEBUG = True
TEMPLATES[0]['OPTIONS']['debug'] = True

Verbose error output:

# Add to component template for debugging
{# props title, description="" #}
<div>
    <h1>DEBUG: title="{{ title }}"</h1>
    <p>DEBUG: description="{{ description }}"</p>
    <div>DEBUG: contents="{{ contents }}"</div>
</div>

Common Error Patterns¶

1. Context variable naming:

<!-- ❌ Wrong: underscore vs hyphen confusion -->
<include:user-card user_name="{{ user.name }}">  <!-- prop: user_name -->
<!-- Component expects: {{ user-name }} not {{ user_name }} -->

<!-- ✅ Correct: consistent naming -->
<include:user-card user-name="{{ user.name }}">  <!-- prop: user-name -->
<!-- Component uses: {{ user-name }} -->

2. Quote handling:

<!-- ❌ Wrong: nested quotes -->
<include:card title="Say "Hello"">

<!-- ✅ Correct: escaped quotes -->
<include:card title="Say &quot;Hello&quot;">

<!-- ✅ Alternative: different quote types -->
<include:card title='Say "Hello"'>

Security and Escaping Issues¶

Understanding Escaping Behavior¶

If you're seeing unexpected escaping or lack of escaping in component attributes:

Problem: Hard-coded strings are being escaped when they shouldn't be

<!-- Expected: text="Don't worry" -->
<!-- Getting: text="Don&#x27;t worry" -->
<include:button text="Don't worry" />

Solution: This indicates an older version behavior. Update to the latest version where hard-coded strings are not escaped.

Problem: Template variables are not being escaped when they should be

<!-- User input with quotes shows unescaped -->
<include:button text="{{ user_input }}" />
<!-- Shows: text="Don't worry" instead of text="Don&#x27;t worry" -->

Solutions:

Django TemplatesJinja2 Templates

<!-- ✅ Variables should be automatically escaped -->
<include:button text="{{ user_input }}" />

<!-- If not escaping, check your Django version and settings -->

<!-- ✅ For consistent escaping, use explicit escaping -->
<include:button text="{{ user_input|e }}" />

<!-- Or configure autoescape in your Jinja2 environment -->

XSS Prevention¶

Problem: Potential XSS vulnerabilities in component attributes

Solution: Never mark user input as safe:

<!-- ❌ Dangerous -->
<include:content html="{{ user_input|safe }}" />

<!-- ✅ Safe -->
<include:content text="{{ user_input }}" />  <!-- Automatically escaped -->

<!-- ✅ Safe with sanitization -->
<include:content html="{{ user_input|bleach|safe }}" />

Security Best Practices¶

For comprehensive security guidance, see the Security Best Practices section.

Key principles: - Hard-coded strings in components are trusted (not escaped) - Template variables are automatically escaped for security - Always validate and sanitize user-provided URLs and content - Use CSRF protection for forms within components

Getting Help¶

Before Asking for Help¶

Check this troubleshooting guide
Enable debug mode
Create a minimal reproduction case
Check recent changes to your templates

When Reporting Issues¶

Include this information:

Django IncludeContents version:
```
pip show django-includecontents
```
Django version:
```
python manage.py version
```
Template engine configuration:
```
# From settings.py
TEMPLATES = [...]
```

Minimal code example:

<!-- Component template -->
{# props title #}
<div>{{ title }}</div>

<!-- Usage -->
<include:my-component title="Test">

Full error traceback:
```
Traceback (most recent call last):
...
```

Community Resources¶

GitHub Issues: Bug reports and feature requests
Documentation: Complete feature documentation
Examples: Working code examples

Prevention Tips¶

Best Practices to Avoid Issues¶

Use consistent naming conventions
Document component props clearly
Test components in isolation
Keep components simple and focused
Use template debugging during development

Regular Maintenance¶

Update Django IncludeContents regularly
Run tests after updates
Review component usage patterns
Clean up unused components

Still Having Issues?¶

If this guide doesn't solve your problem:

Search existing issues
Create a new issue with:
Clear problem description
Minimal reproduction steps
Environment details
Error messages or unexpected behavior