What this usually means
The invoke IPC bridge between your Rust backend and JavaScript frontend has failed to serialize arguments, deserialize the response, or resolve the command name. This is a compile-time contract enforced at runtime — the #[tauri::command] function signature must match exactly what the frontend sends, including argument names, types, and serialization formats. Additionally, the command must be registered with the builder and, on newer Tauri versions, permissions must be explicitly allowed in capabilities config. The error messages are often terse, but they point directly to the broken link.
The first ten minutes — establish facts before touching code.
- 1Check browser console for the exact error message: look for 'command not found', 'invalid args', or a Rust panic trace.
- 2Run the Tauri app with TAURI_DEBUG=1 env var to enable verbose IPC logging: `TAURI_DEBUG=1 cargo tauri dev`.
- 3Verify the command is registered in `tauri::Builder::default().invoke_handler(tauri::generate_handler![my_command])`.
- 4For Tauri v2, check the `capabilities` JSON file under `src-tauri/capabilities/` — ensure the command name is allowed.
- 5Log the exact argument object being sent from JS: `console.log(JSON.stringify(args))` and compare to the Rust struct.
- 6Rust-side, add a `println!` or `log::info!` at the start of the command to confirm it's invoked at all.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchsrc-tauri/src/main.rs or lib.rs — the invoke_handler registration
- searchsrc-tauri/capabilities/ (Tauri v2) — permissions for commands
- searchBrowser DevTools Console — exact invoke error stack
- searchRust stdout/stderr (terminal where `cargo tauri dev` runs) — panic messages
- searchThe JSON serialization of args: use `JSON.stringify()` in JS and `serde_json::to_string_pretty` in Rust for comparison
- searchTauri docs for the specific version: differences between v1 and v2 APIs
- searchThe #[tauri::command] function signature — check types, rename attributes, and return type
Practical causes, not theory. These are the things you will actually find.
- warningCommand not registered in invoke_handler — most common in new apps
- warningArgument type mismatch: JS sends string where Rust expects number, or missing field
- warningTauri v2 capability permissions not granted for the command
- warningCommand name mismatch: Rust function renamed via #[tauri::command(rename_all = "snake_case")] but JS uses camelCase
- warningAsync command without returning a Result or using #[tauri::command] incorrectly
- warningSerialization issue with complex types: enums, nested structures, or types not implementing serde::Serialize/Deserialize
Concrete fix directions. Pick the one that matches your root cause.
- buildEnsure the command is in the generate_handler! macro call.
- buildAdd missing fields to the Rust struct or mark them as Option<T> or default.
- buildFor v2, add the command to the appropriate capability's "allow" list in the JSON file.
- buildUse #[tauri::command(rename_all = "camelCase")] to match JS naming, or change JS to use snake_case.
- buildWrap the command body in a `Result<ReturnType, String>` and return errors explicitly instead of panicking.
- buildSerialize arguments manually with `serde_json::from_str` if the automatic deserialization fails.
A fix you cannot prove is a guess. Close the loop.
- verifiedCall the command from JS console with a minimal object: `invoke('cmd', {key: 'value'}).then(console.log)`.
- verifiedCheck that the Rust side logs the command invocation and returns a value.
- verifiedRun the app with TAURI_DEBUG=1 and confirm IPC messages are logged without errors.
- verifiedFor production builds, test with release mode: `cargo tauri build` and run the binary.
- verifiedWrite an integration test using tauri::test::mock_invoke to simulate the IPC call.
- verifiedMonitor the WebSocket inspector (if using a custom dev server) for IPC frames.
Things that make this bug worse or harder to find.
- warningIgnoring Rust compiler warnings about unused variables or dead code — they often hide registration issues.
- warningAssuming Tauri v1 and v2 APIs are interchangeable; capability system is completely different.
- warningSending complex nested objects without ensuring all fields implement serde traits.
- warningUsing `unwrap()` inside a command — it will panic and kill the app with a verbose error.
- warningForgetting to import `#[derive(Serialize, Deserialize)]` on argument and return types.
- warningHardcoding command names in JS instead of using a constant from Rust to avoid typos.
The Disappearing Command: A Tauri v2 Permission Nightmare
Timeline
- 09:15User reports that the 'save_file' button does nothing. No console error.
- 09:17I check browser console: 'Uncaught (in promise) Error: command not found: save_file'
- 09:20Check invoke_handler: 'generate_handler![save_file]' present.
- 09:22Check Tauri v2 capabilities: 'default.json' exists but does not include 'save_file'.
- 09:25Add 'save_file' to capabilities 'allow' list under 'commands'.
- 09:27Rebuild and test — error persists.
- 09:30Rust log says 'command invoked: save_file' but then panics: 'called `Result::unwrap()` on an `Err` value: SerdeJsonError("missing field `path`")'
- 09:33Check JS call: invoke('save_file', {filePath: '/tmp/test.txt'}) — Rust expects field 'path' not 'filePath'.
- 09:35Fix JS to use 'path' or add rename_all attribute.
- 09:37Test again — works perfectly.
I was called to a broken feature: the 'Save File' button in our document editor. The frontend team swore they'd called the command correctly, but nothing happened. The browser console showed a generic 'command not found' error — a classic Tauri v2 permission issue. I checked the capabilities file and indeed the command wasn't listed. I added it, rebuilt, but the error changed to a serialization failure.
The Rust log revealed the command was now being called, but it panicked because the argument struct expected a field named 'path' while the frontend sent 'filePath'. The frontend team had used camelCase, but our Rust struct used snake_case without a rename attribute. The error message was a Rust unwrap panic, which we'd missed in the terminal because the output was mixed with Vite logs.
After aligning the field names, the command worked. The root cause was a combination of missing permissions and a naming mismatch. We added a rename_all attribute and changed the frontend to use a shared TypeScript type generated from Rust. We also removed all unwrap() calls from commands and replaced them with proper Result returns. The lesson: never assume the error message tells the whole story — always check both sides of the IPC bridge.
Root cause
Missing permission in Tauri v2 capabilities AND argument field name mismatch (camelCase vs snake_case) causing serialization failure.
The fix
Added 'save_file' to capabilities default.json and changed JS invocation to use 'path' key, or added #[tauri::command(rename_all = "camelCase")].
The lesson
Tauri v2 permissions are mandatory, and field naming must match exactly unless rename_all is used. Always log the full error on both sides and avoid unwrap() in commands.
Tauri uses a JSON-RPC-like protocol over a custom IPC channel (stdin/stdout on desktop, WebSocket on mobile). When you call `invoke('cmd', args)` in JS, the frontend serializes the args to JSON and sends a message with the command name. The backend deserializes the JSON into the Rust function's argument type, executes the function, serializes the return value back to JSON, and sends it to the frontend.
Any mismatch in this contract — command name, argument structure, serialization — results in an error. The most common is a missing field in the JSON object: Rust's serde_json expects every non-Option field to be present. If your Rust struct has a field `name: String` but JS sends `{name: undefined}`, that's a missing field error. The fix is to either make the field `Option<String>` or ensure the JS always sends a valid string.
In Tauri v2, every command must be explicitly allowed via a capabilities file (JSON) located under `src-tauri/capabilities/`. The file defines which commands a window or plugin can invoke. If a command is not listed in the `allow` array, the IPC layer will reject it with 'command not found', even if the command is registered in the invoke_handler.
This is a common pitfall for developers migrating from v1. The capabilities file is not generated automatically — you must create it. The default template from `cargo tauri init` may not include custom commands. To fix, edit the capabilities file (e.g., `default.json`) and add the command under `"commands" -> "allow"`. Example: `"commands": { "allow": ["my_cmd"] }`.
Tauri uses serde for serialization. Enums are serialized as JSON strings by default (using the variant name). If your Rust enum has variants with data, serde serializes them as objects with a tag. If the JS sends a plain string, deserialization fails. You can control this with serde attributes like `#[serde(tag = "type")]` or `#[serde(untagged)]`.
For performance, consider using `#[tauri::command]` with `serde_json::Value` for dynamic arguments, but you lose type safety. A better approach is to define a clear schema and use TypeScript types generated from Rust via `tauri-specta` or similar tools to ensure frontend and backend stay in sync.
Async commands must return a `Result<T, E>` where E implements `Into<InvokeError>`. If you use `unwrap()` inside an async command, the panic will be caught by the Tauri runtime and returned as a serialized error. However, the error message is often unhelpful (just 'called Result::unwrap() on an Err value'). Always propagate errors with `?` or `map_err` to return meaningful messages.
Additionally, async commands that spawn tasks must ensure the task handle is awaited or detached properly. Forgetting to `.await` a future will cause the command to return immediately with a default value (or hang). Use `tokio::spawn` only for fire-and-forget tasks; for commands, keep the async context.
Set `TAURI_DEBUG=1` before running `cargo tauri dev` to enable verbose IPC logging. This prints every invoke call, its arguments, and the response/error. It's the fastest way to see if the command is being called at all and what data is flowing. Combine with `RUST_LOG=debug` to see serde deserialization details.
If the error is 'invalid args', enable `RUST_LOG=serde_json=debug` to see exactly where deserialization fails. For complex apps, add a custom middleware or use the `tauri::ipc::Invoke` struct to intercept calls for logging.
Frequently asked questions
Why does my command work in development but fail in production build?
Production builds strip debug symbols and may optimize away unused functions. Ensure the command is not conditionally compiled with `#[cfg(debug_assertions)]`. Also, Tauri v2 production builds use the capabilities file from the bundle — verify the file is included in the final binary and hasn't been overwritten. Another common cause: the JS frontend is minified and the invoke call string may be mangled if you're not using a constant.
How do I pass complex nested objects as command arguments?
Define a Rust struct with `#[derive(Serialize, Deserialize)]` and use it as the argument type. In JS, pass a matching JSON object. Ensure all nested fields also implement Serialize/Deserialize. For optional fields, use `Option<T>`. If you need dynamic keys, use `HashMap<String, Value>` or `serde_json::Value`. Avoid large nested objects — consider splitting into multiple commands.
What does 'command not found' mean in Tauri v2?
It means the IPC layer could not find the command. Two possibilities: (1) the command is not registered in the `invoke_handler`, or (2) the command is not allowed in the capabilities file. Check both. In v1, only registration mattered; in v2, capabilities are enforced.
Can I call a Rust command synchronously from JS?
No, Tauri's IPC is asynchronous by design. `invoke` returns a `Promise`. If you need synchronous behavior, you must restructure your code to use async/await or use a custom protocol via Tauri's `tauri::api::process::Command` for synchronous child processes, but that's separate from the invoke system.
Why does my enum argument cause a deserialization error?
Serde deserializes enums by default as a string matching the variant name. If your enum has data fields, you need to use `#[serde(tag = "type")]` or `#[serde(untagged)]`. Ensure the JS object matches the expected format. For example, if Rust enum is `enum Foo { Bar(i32), Baz }`, JS must send `{"Bar": 42}` or `"Bar"` depending on serde settings.