{"record":{"id":"9e9602d3397cbcd9","repo":"tauri-apps/tauri","slug":"failed-to-setup-custom-handlebar-template","errorCode":null,"errorMessage":"Failed to setup custom handlebar template","messagePattern":"Failed to setup custom handlebar template","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tauri-bundler/src/bundle/windows/msi/mod.rs","lineNumber":742,"sourceCode":"  if let Some(file_associations) = settings.file_associations() {\n    data.insert(\"file_associations\", to_json(file_associations));\n  }\n\n  if let Some(protocols) = settings.deep_link_protocols() {\n    let schemes = protocols\n      .iter()\n      .flat_map(|p| &p.schemes)\n      .collect::<Vec<_>>();\n    if !schemes.is_empty() {\n      data.insert(\"deep_link_protocols\", to_json(schemes));\n    }\n  }\n\n  if let Some(path) = custom_template_path {\n    handlebars\n      .register_template_string(\"main.wxs\", fs::read_to_string(path)?)\n      .map_err(|e| e.to_string())\n      .expect(\"Failed to setup custom handlebar template\");\n  } else {\n    handlebars\n      .register_template_string(\"main.wxs\", include_str!(\"./main.wxs\"))\n      .map_err(|e| e.to_string())\n      .expect(\"Failed to setup handlebar template\");\n  }\n\n  if enable_elevated_update_task {\n    data.insert(\n      \"msiexec_args\",\n      to_json(\n        settings\n          .updater()\n          .map(|updater| updater.msiexec_args)\n          .map(|args| args.join(\" \"))\n          .unwrap_or_else(|| \"/passive\".to_string()),\n      ),\n    );","sourceCodeStart":724,"sourceCodeEnd":760,"githubUrl":"https://github.com/tauri-apps/tauri/blob/460ec35447493200d64290dd7f015d5a91d0fd58/crates/tauri-bundler/src/bundle/windows/msi/mod.rs#L724-L760","documentation":"Panic from `.expect(\"Failed to setup custom handlebar template\")` in `build_wix_app_installer`. After reading the user's custom `main.wxs` template file, the bundler registers it with Handlebars; if the template contains invalid Handlebars syntax (unbalanced `{{#if}}`/`{{/if}}`, bad helpers, malformed expressions), `register_template_string` fails and the bundler panics. It is distinct from the built-in template path: the built-in `main.wxs` cannot fail, only a user-supplied one can.","triggerScenarios":"Providing a custom WiX template via `windows.wix.template` in tauri.conf.json (or the equivalent bundle config) whose content is not valid Handlebars syntax; the file reads fine (`fs::read_to_string` succeeded) but template compilation fails.","commonSituations":"Hand-edited WiX templates with mismatched block tags, copying a template from an incompatible Tauri/WiX version whose expected variables changed, missing closing braces or stray `{{` characters, or referencing unregistered helpers in the custom template.","solutions":["Validate the custom template's Handlebars syntax: check every `{{#each}}`/`{{#if}}` has a matching `{{/each}}`/`{{/if}}` and escape literal `{{` as `{{{\"{{\"}}}` style raw blocks where needed","Start from the built-in template shipped with your tauri-bundler version (`main.wxs` in the crate) and modify incrementally, testing after each change","Remove or correct unsupported helper calls; only helpers registered by tauri-bundler are available in the template","Temporarily unset `windows.wix.template` to confirm the built-in template bundles, then bisect your custom template"],"exampleFix":"// tauri.conf.json -> custom main.wxs\n// before\n{{#if productLanguage}}\n  <Product Language=\"en-US\"/>\n{{/if productLanguage}}\n// after (balanced close)\n{{#if productLanguage}}\n  <Product Language=\"en-US\"/>\n{{/if}}","handlingStrategy":"try-catch","validationCode":"// pre-validate custom template balance before configuring it\nlet tpl = std::fs::read_to_string(custom_wxs_path)?;\nlet opens = tpl.matches(\"{{#\").count();\nlet closes = tpl.matches(\"{{/\").count();\nif opens != closes {\n    return Err(format!(\n        \"unbalanced handlebars blocks: {} open vs {} close\",\n        opens, closes\n    ));\n}","typeGuard":null,"tryCatchPattern":"// mirror the bundler's logic locally to get a real error instead of a panic\nmatch handlebars.register_template_string(\"main.wxs\", tpl) {\n    Ok(_) => {},\n    Err(e) => return Err(anyhow!(\"invalid custom WiX template: {e}\")),\n}","preventionTips":["Start from the built-in main.wxs of your exact tauri-bundler version and edit incrementally","After every template edit, run the bundler early to catch syntax errors fast","Balance every {{#if}}/{{#each}} with its matching close tag","Escape literal braces that WiX/Handlebars could misinterpret","Keep custom templates versioned and re-diff them when upgrading Tauri"],"tags":["handlebars","wix","windows","template","panic"],"backgroundTag":"template-parse-failed","analyzedSha":"460ec35447493200d64290dd7f015d5a91d0fd58","analyzedAt":"2026-09-18T23:55:51.277Z","contentChangedAt":"2026-09-18T23:55:51.277Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}