What causes "Either a `templates/` folder or a theme is required" in getzola/zola?

Create a `templates/` directory at the site root with at least an index.html

Either a `templates/` folder or a theme is required

Error message

Either a `templates/` folder or a theme is required

What it means

`load_tera` requires at least one template source: either a `templates/` directory at the site root or a configured theme providing one. If neither exists it bails with this message, since Tera would have no templates to load.

Source

Thrown at components/templates/src/lib.rs:139

    // Add builtin templates
    for (name, content) in BUILTIN_TEMPLATES {
        templates.push((name.to_string(), content.to_string()));
    }

    // Validate theme exists if configured
    let site_tpl_dir = path.join("templates");
    let theme_tpl_dir =
        config.theme.as_ref().map(|t| path.join("themes").join(t).join("templates"));

    if let Some(ref theme_dir) = theme_tpl_dir
        && !theme_dir.exists()
    {
        bail!("Theme `{}` is missing a templates folder", config.theme.as_ref().unwrap());
    }

    if !site_tpl_dir.exists() && theme_tpl_dir.is_none() {
        bail!("Either a `templates/` folder or a theme is required");
    }

    // Load theme templates first (lower priority)
    if let Some(ref theme) = config.theme {
        let pattern = format!(
            "{}/themes/{theme}/templates/**/*.{{html,xml,md,txt,json,ics}}",
            glob_base(path)
        );
        for (file_path, name) in tera::load_from_glob(&pattern)? {
            // "page.html" → "sample/templates/page.html"
            let name = format!("{theme}/templates/{name}");
            let content = fs::read_to_string(&file_path)
                .with_context(|| format!("Failed to read '{}'", file_path.display()))?;
            templates.push((name, content));
        }
    }

    // Load site templates (higher priority, will override theme templates)

View on GitHub (pinned to 61d3082821)

Solutions

Create a `templates/` directory at the site root with at least an index.html
Or set `theme = "..."` in config.toml with the theme installed under `themes/`
Run the command from the correct project root directory

Example fix

// before
# no templates/ dir, no theme set
// after
$ mkdir templates && echo '...' > templates/index.html
# or set theme = "hyde" in config.toml

Defensive patterns

Strategy: validation

Validate before calling

let has_templates = Path::new("templates").is_dir();
let has_theme = config.theme.is_some();
if !has_templates && !has_theme {
    panic!("create templates/ or set theme in config.toml");
}

Try / catch

match load_tera(base_path, &config) {
    Ok(t) => use(t),
    Err(e) if e.to_string().contains("Either a `templates/` folder") => {
        eprintln!("run from project root; create templates/ or set a theme");
    }
    Err(e) => return Err(e),
}

Prevention

Always run zola from the site root containing config.toml
Keep at least templates/index.html in the project
Commit the templates/ directory (or theme config) to version control

When it happens

Trigger: Running a site build/serve where `templates/` does not exist at the project root AND `config.theme` is None/unset in config.toml.

Common situations: Freshly initialized or emptied project where the templates folder was deleted or never created; running zola from the wrong directory; config.toml missing the `theme` key after removing templates.

Related errors

AI-assisted analysis of getzola/zola@61d3082821 (2026-09-03). Data as JSON: /api/errors/d6d63d53ecc84283. Report an issue: GitHub.