tauri-apps/tauri · error

Failed to setup handlebar template

Error message

Failed to setup handlebar template

What it means

The MSI bundler registers its built-in main.wxs (embedded via include_str!) as a Handlebars template. The built-in template ships and is tested with the crate, so this expect indicates a corrupted/vendored install or a handlebars dependency regression rather than anything in your tauri.conf.json.

Source

Thrown at crates/tauri-bundler/src/bundle/windows/msi/mod.rs:743

    let schemes = protocols
      .iter()
      .flat_map(|p| &p.schemes)
      .collect::<Vec<_>>();
    if !schemes.is_empty() {
      data.insert("deep_link_protocols", to_json(schemes));
    }
  }

  if let Some(path) = custom_template_path {
    handlebars
      .register_template_string("main.wxs", fs::read_to_string(path)?)
      .map_err(|e| e.to_string())
      .expect("Failed to setup custom handlebar template");
  } else {
    handlebars
      .register_template_string("main.wxs", include_str!("./main.wxs"))
      .map_err(|e| e.to_string())
      .expect("Failed to setup handlebar template");
  }

  if enable_elevated_update_task {
    data.insert(
      "msiexec_args",
      to_json(
        settings
          .updater()
          .map(|updater| updater.msiexec_args)
          .map(|args| args.join(" "))
          .unwrap_or_else(|| "/passive".to_string()),
      ),
    );

    // Create the update task XML
    let skip_uac_task = Handlebars::new();
    let xml = include_str!("./update-task.xml");
    let update_content = skip_uac_task.render_template(xml, &data)?;

View on GitHub (pinned to 52e4b6e71d)

Solutions

1. Install a matching official release: cargo install tauri-cli --locked (or the npm/pnpm/cargo-binstall equivalent) and rebuild
2. Clear the cached tauri-bundler sources (cargo registry cache) and rebuild so the pristine template is re-extracted
3. If vendoring the bundler, ensure local main.wxs edits compile against the pinned handlebars version before shipping

# confirm the CLI and crate pair are an official matching release
cargo tauri --version
cargo tree -i tauri-bundler 2>/dev/null || true

When it happens

Trigger: tauri build --bundles msi with no custom template configured, where the embedded main.wxs fails Handlebars compilation — e.g. a patched or vendored tauri-bundler whose template edits do not compile, or a dependency resolution that changes Handlebars parsing behavior.

Common situations: Vendored/forked tauri-bundler with local template edits; downgrading handlebars alongside the bundler; corrupted cargo registry cache serving mismatched crate sources.

Related errors

• Failed to setup custom handlebar template
• Language {} not found. It must be one of {}
• Failed to create locale file
• failed to extract merge module filename
• failed to convert merge module filename to string

AI-assisted analysis of tauri-apps/tauri@52e4b6e71d (2026-08-20). Data as JSON: /api/errors/be67ded5a564f493. Report an issue: GitHub.