tauri-errors-runtime

tauri-errors-runtime

Quick Diagnosis

When a Tauri 2 app crashes or behaves unexpectedly at runtime, identify the error category:

Runtime Error Categories:
1. State panics       --> Type mismatch, unmanaged state
2. IPC errors         --> Command not found, permission denied, argument mismatch
3. Window errors      --> Window/webview not found, already destroyed
4. Plugin errors      --> Plugin not initialized, missing permissions
5. Event errors       --> Invalid event name, listener leaks
6. Asset errors       --> File not found, protocol not configured
7. Panic/crash        --> Unhandled panic, thread panic

ALWAYS check the terminal/console output -- Tauri prints panics and errors to stderr.

NEVER ignore unwrap() calls in production code -- they cause panics that crash the app.

---

Error Lookup Table: State Management

ERR-R001: State type mismatch panic

Error: state not managed for field "state" on command "my_command" or called Option::unwrap() on a None value at runtime.

Cause: The type in State<'_, T> does not match the type passed to manage(). This is a RUNTIME panic, not a compile error.

// WRONG -- register Mutex<Counter>, access as Counter
app.manage(Mutex::new(Counter::default()));

#[tauri::command]
fn bad(state: State<'_, Counter>) { }  // PANIC at runtime!

// CORRECT -- types must match exactly
app.manage(Mutex::new(Counter::default()));

#[tauri::command]
fn good(state: State<'_, Mutex<Counter>>) {
    let mut counter = state.lock().unwrap();
    counter.value += 1;
}

ALWAYS ensure the generic type in State<'_, T> matches exactly what was passed to manage().

ERR-R002: State not registered

Error: state not managed for field "state" -- app panics when the command is first invoked.

Cause: Forgot to call .manage() on the Builder or in setup().

Fix: ALWAYS register state before it is accessed:

tauri::Builder::default()
    .manage(AppConfig { api_url: "https://api.example.com".into() })
    .manage(Mutex::new(Counter::default()))
    // ... state must be registered before commands use it