tauri-errors-build

name	tauri-errors-build
description	Use when encountering Tauri 2 build errors, bundler failures, or platform-specific compilation issues. Prevents chasing phantom failures from stale build artifacts and misidentifying the failing build pipeline phase. Covers Cargo compilation failures, bundler errors, code signing failures, Linux dependencies, mobile builds, and CI/CD failures. Keywords: tauri build error, cargo compile, bundler error, code signing, linker error, NSIS, WiX, CI/CD failure.
license	MIT
compatibility	Designed for Claude Code. Requires Tauri 2.x.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

tauri-errors-build

Quick Diagnosis

When a Tauri 2 build fails, identify the phase first:

Build Pipeline Phases:
1. Frontend build   (beforeBuildCommand)  --> JS/TS errors
2. Cargo compile    (rustc)               --> Rust compilation errors
3. Bundler          (NSIS/WiX/DMG/deb)    --> Platform packaging errors
4. Code signing     (codesign/signtool)   --> Signing/notarization errors

ALWAYS read the FULL error output. The root cause is often buried above the final error message.

NEVER skip cargo clean when troubleshooting persistent compilation errors -- stale build artifacts cause phantom failures.

---

Error Lookup Table: Cargo Compilation

ERR-B001: Command function visibility in lib.rs

Error: error[E0255]: the name X is defined multiple times or cryptic macro expansion errors.

Cause: Command functions defined directly in src-tauri/src/lib.rs are marked pub.

Fix: ALWAYS remove pub from command functions in lib.rs. Commands in separate modules MUST be pub.

// WRONG -- in lib.rs
#[tauri::command]
pub fn greet(name: String) -> String { ... }

// CORRECT -- in lib.rs
#[tauri::command]
fn greet(name: String) -> String { ... }

// CORRECT -- in src-tauri/src/commands.rs (separate module)
#[tauri::command]
pub fn greet(name: String) -> String { ... }

ERR-B002: Missing Serialize on error type

Error: the trait bound MyError: Serialize is not satisfied

Cause: Command return type Result<T, E> requires E to implement serde::Serialize.

Fix: ALWAYS implement Serialize manually for error enums that use thiserror:

#[derive(Debug, thiserror::Error)]
enum AppError {
    #[error(transparent)]
    Io(#[from] std::io::Error),
    #[error("not found: {0}")]
    NotFound(String),
}

impl serde::Serialize for AppError {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where S: serde::ser::Serializer {
        serializer.serialize_str(self.to_string().as_ref())
    }
}

ERR-B003: Borrowed references in async commands

Error: implementation of FnOnce is not general enough or lifetime errors in async command signatures.

Cause: Async commands cannot use &str directly due to spawning on the tokio runtime.

Fix: Use owned types (String) or wrap return in Result:

// WRONG
#[tauri::command]
async fn process(value: &str) -> String { value.to_uppercase() }

// CORRECT -- option 1: owned type
#[tauri::command]
async fn process(value: String) -> String { value.to_uppercase() }

// CORRECT -- option 2: wrap in Result
#[tauri::command]
async fn process(value: &str) -> Result<String, ()> { Ok(value.to_uppercase()) }

ERR-B004: Multiple invoke_handler calls

Error: Commands silently not working -- no compilation error.

Cause: Only the LAST .invoke_handler() call on Builder takes effect. Multiple calls do NOT merge.

Fix: ALWAYS use a single generate_handler![] with all commands:

// WRONG -- only cmd2 works
tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![cmd1])
    .invoke_handler(tauri::generate_handler![cmd2])

// CORRECT
tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![cmd1, cmd2])

ERR-B005: Mobile crate-type missing

Error: cannot produce cdylib for app_lib or linking errors on tauri android build / tauri ios build.

Cause: Cargo.toml missing required crate types for mobile targets.

Fix: ALWAYS include all three crate types when targeting mobile:

[lib]
name = "app_lib"
crate-type = ["staticlib", "cdylib", "rlib"]

ERR-B006: Missing mobile entry point

Error: App crashes immediately on mobile, or tauri android build / tauri ios build fails with missing symbol errors.

Cause: Missing #[cfg_attr(mobile, tauri::mobile_entry_point)] macro or incorrect project structure.

Fix: ALWAYS split into lib.rs + main.rs for mobile support:

// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// src-tauri/src/main.rs
fn main() {
    app_lib::run();
}

---

Error Lookup Table: Linux Dependencies

ERR-B010: Missing webkit2gtk

Error: Package webkit2gtk-4.1 was not found or error: could not find system library 'webkit2gtk-4.1'

Fix: Install required system dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
    libwebkit2gtk-4.1-dev \
    libappindicator3-dev \
    librsvg2-dev \
    patchelf

# Fedora
sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel

# Arch
sudo pacman -S webkit2gtk-4.1 libappindicator-gtk3 librsvg

NEVER install libwebkit2gtk-4.0-dev -- Tauri 2 requires the 4.1 variant.

ERR-B011: Missing build tools

Error: linker cc not found or failed to run custom build command

Fix: Install base build tools:

sudo apt-get install -y build-essential curl wget file libssl-dev libgtk-3-dev \
    libayatana-appindicator3-dev

---

Error Lookup Table: Bundler Errors

ERR-B020: NSIS installer failure (Windows)

Error: NSIS Error or MakeNSIS exited with error

Common causes and fixes:

1. Path too long -- shorten productName or move project closer to drive root
2. Missing NSIS -- install via choco install nsis or winget install NSIS.NSIS
3. Icon format wrong -- NSIS requires .ico files with specific sizes

ERR-B021: WiX/MSI failure (Windows)

Error: candle.exe exited with error or light.exe exited with error

Fix: Install WiX Toolset v3: dotnet tool install --global wix

ERR-B022: DMG creation failure (macOS)

Error: hdiutil: create failed or DMG size errors

Common causes: Disk space insufficient, or icon file path incorrect in tauri.conf.json.

ERR-B023: AppImage failure (Linux)

Error: AppImage bundling failed or missing appimagetool

Fix: Ensure FUSE is available. On Ubuntu 22.04+:

sudo apt-get install -y libfuse2

ERR-B024: WebView2 bootstrapper (Windows)

Error: Failed to download WebView2 bootstrapper

Fix: Configure offline installation in tauri.conf.json:

{
  "bundle": {
    "windows": {
      "webviewInstallMode": "offlineInstaller"
    }
  }
}

---

Error Lookup Table: Code Signing

ERR-B030: macOS unsigned app blocked

Error: "MyApp" is damaged and can't be opened or Gatekeeper rejection.

Fix: At minimum use ad-hoc signing for testing:

{
  "bundle": {
    "macOS": {
      "signingIdentity": "-"
    }
  }
}

For distribution, ALWAYS use a proper Developer ID certificate.

ERR-B031: macOS notarization failure

Error: The signature of the binary is invalid or notarytool errors.

Checklist:

1. Hardened runtime enabled: "hardenedRuntime": true
2. Signing identity correct: "Developer ID Application: Name (TEAMID)"
3. Environment variables set: APPLE_API_ISSUER, APPLE_API_KEY, APPLE_API_KEY_PATH
4. Certificate not expired

ERR-B032: Windows Authenticode failure

Error: SignTool Error or certificate thumbprint not found

Checklist:

1. Certificate installed in current user store
2. Thumbprint matches: "certificateThumbprint": "A1B2..."
3. Timestamp URL reachable: "timestampUrl": "http://timestamp.comodoca.com"

---

Error Lookup Table: CI/CD

ERR-B040: GitHub Actions Linux build fails

Error: Various dependency errors in CI.

Fix: ALWAYS include the Linux dependency installation step:

- name: Install Linux dependencies
  if: runner.os == 'Linux'
  run: |
    sudo apt-get update
    sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev

ERR-B041: GitHub token permissions

Error: Resource not accessible by integration or 403 on release creation.

Fix: Set permissions in workflow:

permissions:
  contents: write

And ensure repository Settings > Actions > General > Workflow permissions is set to "Read and write."

ERR-B042: Updater artifact build fails

Error: TAURI_SIGNING_PRIVATE_KEY must be set

Cause: "createUpdaterArtifacts": true in config but no signing key.

Fix: Either set the environment variable in CI secrets, or set "createUpdaterArtifacts": false if not using auto-updater.

ERR-B043: Cross-compilation target missing

Error: error[E0463]: can't find crate for std when building for a different architecture.

Fix: Install the target toolchain:

# macOS universal binary
rustup target add aarch64-apple-darwin x86_64-apple-darwin

# Android
rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android

# iOS
rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim

---

Diagnostic Decision Tree

Build failed?
|
+-- Is it a Rust compilation error?
|   +-- Type mismatch in command? --> Check ERR-B001, ERR-B002, ERR-B003
|   +-- Symbol/linking error? --> Check ERR-B005, ERR-B006, ERR-B043
|   +-- Commands not found at runtime? --> Check ERR-B004
|
+-- Is it a system dependency error?
|   +-- Linux? --> Check ERR-B010, ERR-B011
|   +-- Windows WebView2? --> Check ERR-B024
|
+-- Is it a bundler error?
|   +-- Windows NSIS/WiX? --> Check ERR-B020, ERR-B021
|   +-- macOS DMG? --> Check ERR-B022
|   +-- Linux AppImage? --> Check ERR-B023
|
+-- Is it a code signing error?
|   +-- macOS? --> Check ERR-B030, ERR-B031
|   +-- Windows? --> Check ERR-B032
|
+-- Is it a CI/CD error?
    +-- Linux deps? --> Check ERR-B040
    +-- Permissions? --> Check ERR-B041
    +-- Updater keys? --> Check ERR-B042
    +-- Cross-compile? --> Check ERR-B043

---

General Troubleshooting Steps

1. ALWAYS run cargo clean in src-tauri/ before retrying
2. ALWAYS check tauri info output for environment diagnostics
3. ALWAYS verify tauri.conf.json has valid JSON (use schema validation)
4. NEVER ignore warnings -- they often become errors in release builds
5. NEVER assume a build works on all platforms because it works on one

---

Reference Links

• references/methods.md -- Build commands, environment variables, configuration keys
• references/examples.md -- Working build configurations and CI/CD templates
• references/anti-patterns.md -- Build configuration mistakes with fixes

Official Sources

• https://v2.tauri.app/start/prerequisites/
• https://v2.tauri.app/distribute/
• https://v2.tauri.app/develop/debug/