getzola/zola · error

no templates registered

Error message

no templates registered

What it means

The global ZOLA_TERA LazyLock registers fallback prefixes on a default Tera instance with .expect("no templates registered"). Tera's set_fallback_prefixes only fails when the instance has zero templates, but here it is called before registering any, relying on the fact this check passes for default instances; if the ordering or Tera version changes, first access panics.

Source

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

const BUILTIN_TEMPLATES: &[(&str, &str)] = &[
    ("__zola_builtins/404.html", include_str!("builtins/404.html")),
    ("__zola_builtins/atom.xml", include_str!("builtins/atom.xml")),
    ("__zola_builtins/rss.xml", include_str!("builtins/rss.xml")),
    ("__zola_builtins/sitemap.xml", include_str!("builtins/sitemap.xml")),
    ("__zola_builtins/robots.txt", include_str!("builtins/robots.txt")),
    ("__zola_builtins/split_sitemap_index.xml", include_str!("builtins/split_sitemap_index.xml")),
    ("__zola_builtins/anchor-link.html", include_str!("builtins/anchor-link.html")),
    ("__zola_builtins/summary-cutoff.html", include_str!("builtins/summary-cutoff.html")),
    // This is not overridable by the user
    (REDIRECT_TPL_NAME, include_str!("builtins/internal/alias.html")),
];

pub static ZOLA_TERA: LazyLock<Tera> = LazyLock::new(|| {
    let mut tera = Tera::default();

    // Only really needed for tests
    tera.set_fallback_prefixes(vec!["__zola_builtins/".to_string()])
        .expect("no templates registered");

    // tera-contrib stuff
    tera.register_filter("base64_encode", tera_contrib::base64::b64_encode);
    tera.register_filter("base64_decode", tera_contrib::base64::b64_decode);
    tera.register_filter("regex_replace", tera_contrib::regex::RegexReplace::default());
    tera.register_filter("striptags", tera_contrib::regex::striptags);
    tera.register_filter("spaceless", tera_contrib::regex::spaceless);
    tera.register_filter("urlencode", tera_contrib::urlencode::urlencode);
    tera.register_filter("urlencode_strict", tera_contrib::urlencode::urlencode_strict);
    tera.register_filter("json_encode", tera_contrib::json::json_encode);
    tera.register_filter("filesizeformat", tera_contrib::filesize_format::filesize_format);
    tera.register_filter("format", tera_contrib::format::format);
    tera.register_filter("slugify", tera_contrib::slug::slug);
    tera.register_filter("date", tera_contrib::dates::date);
    tera.register_filter("shuffle", tera_contrib::rand::shuffle);

    tera.register_function("get_random", tera_contrib::rand::get_random);

View on GitHub (pinned to 61d3082821)

Solutions

1. Register at least one template (or add templates via add_raw_template) before calling set_fallback_prefixes
2. Replace expect with graceful handling that logs and continues without fallback prefixes
3. Pin/verify the tera dependency version matches the expected set_fallback_prefixes behavior

Example fix

// before
tera.set_fallback_prefixes(vec!["__zola_builtins/".to_string()])
    .expect("no templates registered");
// after
tera.add_raw_template("__zola_builtins/anchor-link.html", "").ok();
tera.set_fallback_prefixes(vec!["__zola_builtins/".to_string()])
    .expect("no templates registered");

// ensure at least one template exists before set_fallback_prefixes
if tera.templates.is_empty() {
    tera.add_raw_template("__zola_builtins/placeholder.html", "")
        .expect("failed to register placeholder template");
}

if let Err(e) = tera.set_fallback_prefixes(vec!["__zola_builtins/".to_string()]) {
    eprintln!("warning: fallback prefixes not set: {}", e);
}

When it happens

Trigger: First access of ZOLA_TERA when set_fallback_prefixes is called on a Tera instance that contains no templates (Tera::default plus a Tera version whose fallback check requires templates).

Common situations: Using this static in unit tests after a Tera upgrade changed set_fallback_prefixes semantics; reordering the initialization code so it runs after an empty-instance check.

Related errors

• {:?} is not inside the base site directory {:?}
• Either a `templates/` folder or a theme is required
• reqwest client build
• result cache lock
• response client lock

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