Template Not Found

Fix template loading errors

2 min read 386 words

FixTemplateNotFoundErrorexceptions.

The Error

TemplateNotFoundError: Template 'bsae.html' not found in: templates/

Common Causes

1. Typo in Template Name

# ❌ Typo
env.get_template("bsae.html")

# ✅ Correct
env.get_template("base.html")

Fix: Check the template filename spelling.

2. Wrong Path

# ❌ Wrong path
env.get_template("templates/page.html")

# ✅ Relative to loader root
env.get_template("page.html")

Fix: Paths are relative to the loader's search directories.

3. No Loader Configured

# ❌ No loader
env = Environment()
env.get_template("page.html")  # Raises RuntimeError

# ✅ Configure loader
env = Environment(loader=FileSystemLoader("templates/"))

Fix: Always configure a loader forget_template().

4. Wrong Search Directory

# ❌ Wrong directory
loader = FileSystemLoader("template/")  # Missing 's'

# ✅ Correct directory
loader = FileSystemLoader("templates/")

Fix: Verify the directory path exists.

5. Extends/Include Path Error

{# ❌ Wrong path #}
{% extends "../base.html" %}

{# ✅ From loader root #}
{% extends "layouts/base.html" %}

Fix: Use paths relative to loader root, not current file.

Solutions

List Available Templates

loader = FileSystemLoader("templates/")
print(loader.list_templates())
# ['base.html', 'pages/home.html', 'components/button.html']

Use Absolute Paths

from pathlib import Path

templates_dir = Path(__file__).parent / "templates"
loader = FileSystemLoader(templates_dir)

Multiple Search Paths

loader = FileSystemLoader([
    "templates/",         # Primary
    "shared/templates/",  # Fallback
])

Debug Template Loading

def load_template(name):
    try:
        return env.get_template(name)
    except TemplateNotFoundError:
        print(f"Template '{name}' not found")
        print(f"Search paths: {env.loader._paths}")
        print(f"Available: {env.loader.list_templates()}")
        raise

Check File System

# Verify template exists
ls -la templates/

# Find templates
find . -name "*.html" -type f

Common Patterns

Project Structure

myproject/
├── app.py
└── templates/
    ├── base.html
    ├── layouts/
    │   └── sidebar.html
    └── pages/
        └── home.html

# In app.py
loader = FileSystemLoader("templates/")
env.get_template("base.html")
env.get_template("layouts/sidebar.html")
env.get_template("pages/home.html")

Package Templates

from pathlib import Path
import mypackage

templates = Path(mypackage.__file__).parent / "templates"
loader = FileSystemLoader(templates)

Prevention

Validate on Startup

def validate_templates():
    required = ["base.html", "error.html", "home.html"]
    for name in required:
        try:
            env.get_template(name)
        except TemplateNotFoundError:
            raise RuntimeError(f"Required template missing: {name}")

validate_templates()

Use Constants

class Templates:
    BASE = "base.html"
    HOME = "pages/home.html"
    ERROR = "error.html"

env.get_template(Templates.HOME)

See Also