tauri-apps/tauri · error

Failed to setup custom handlebar template

Error message

Failed to setup custom handlebar template

What it means

When bundle.windows.wix.template points at a custom WiX template, the MSI bundler registers the file's contents as a Handlebars template. Registration parses the template, and a Handlebars syntax error (unbalanced {{ }}, malformed block) turns into this expect and aborts the run. A missing or unreadable template file instead surfaces earlier as the propagated fs error, not this panic.

Source

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

  if let Some(file_associations) = settings.file_associations() {
    data.insert("file_associations", to_json(file_associations));
  }

  if let Some(protocols) = settings.deep_link_protocols() {
    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()),
      ),
    );

View on GitHub (pinned to 52e4b6e71d)

Solutions

1. Parse-check the template with Handlebars before bundling (e.g. node -e with handlebars.compile) and fix the reported syntax error
2. Diff the custom template against the stock main.wxs of the tauri version you build with, and re-apply edits incrementally
3. Temporarily remove the wix.template config to confirm the built-in path bundles fine, isolating the fault to the custom file
4. Regenerate the custom template from the current tauri release's main.wxs rather than carrying old edits forward

Example fix

<!-- custom template — before -->
<?if {{{{build_arch}}}} = "x64" ?>  <!-- stray/unclosed Handlebars expressions -->

<!-- after -->
{{#if (eq build_arch "x64")}}
  <Condition Message="x64 only">VersionNT64</Condition>
{{/if}}

# preflight: parse-check the custom WiX template with Handlebars before tauri build
node -e 'const h=require("handlebars");const s=require("fs").readFileSync(process.argv[1],"utf8");try{h.compile(s);console.log("template OK")}catch(e){console.error(e.message);process.exit(1)}' custom.wxs

When it happens

Trigger: tauri build --bundles msi with a custom template containing invalid Handlebars syntax — unclosed {{#if}}/{{/if}}, stray {{, or expressions that do not compile against the bundler's handlebars version.

Common situations: Copying the stock main.wxs and hand-editing it; using WiX preprocessor syntax inside Handlebars expressions; carrying a template forward across tauri versions whose expected helpers/placeholders changed.

Related errors

• Failed to setup 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/9e9602d3397cbcd9. Report an issue: GitHub.