Error Types & Handling
Relevant source files
The following files were used as context for generating this wiki page:
The tauri-plugin-serialplugin provides a robust error handling system that bridges the gap between low-level hardware interactions and high-level JavaScript APIs. This system ensures that errors occurring during serial port operations—such as physical disconnection, permission issues, or data transmission failures—are accurately captured in Rust/Kotlin/Swift and communicated to the frontend.
The architecture uses a unified Error type in Rust that wraps standard IO errors and plugin-specific messages, allowing for consistent error propagation across the Tauri IPC (Inter-Process Communication) layer.
Sources: src/error.rs, src/lib.rs:100-115, debug.md:15-20
Rust Backend Error Structure
The backend implementation utilizes the thiserror crate to define a comprehensive Error enum. This structure is designed to handle various failure scenarios encountered during serial communication.
Error Variants
The core Error enum categorizes failures into three primary types:
- Io: Wraps standard
std::io::Error, covering low-level system failures like "Port not found" or "Access denied." - SerialPort: Specifically for errors returned by the underlying
serialportcrate. - String: A flexible variant for custom plugin-level error messages.
Sources: src/error.rs:5-15, src/tests/error_test.rs:10-25
Error Flow and Conversion
Rust errors are converted into strings before being sent to the frontend via Tauri's invoke system.
The implementation ensures that Error implements Send, Sync, and Clone, making it safe for use in multi-threaded asynchronous contexts common in Tauri plugins.
Sources: src/error.rs:20-40, src/tests/error_test.rs:45-50
Frontend JavaScript Error Handling
The guest-js API wraps backend calls in try...catch blocks and provides explicit validation logic to prevent invalid requests from reaching the backend.
Validation Errors
Before an IPC call is made, the SerialPort class validates parameters. If validation fails, it throws a string error immediately.
- Empty Path: Throws "path Can not be empty!"
- Zero BaudRate: Throws "baudRate Can not be empty!"
- Type Mismatch: Throws "Argument type error! Expected type..."
Sources: guest-js/index.ts:250-270, tests/error-handling.test.ts:150-160
Connection Lifecycle Errors
The frontend tracks the state of the port using an isOpen flag. This prevents redundant or invalid operations.
| Scenario | Behavior | Error Message |
|---|---|---|
| Writing to closed port | Rejection | serial port {path} not opened! |
| Opening already open port | Early Resolve | None (Silent success) |
| Closing already closed port | Early Resolve | None (Silent success) |
Sources: guest-js/index.ts:300-320, tests/error-handling.test.ts:165-180
Mobile (Android) Specific Error Handling
For Android, the plugin includes enhanced type safety and logging to handle the specificities of USB-Serial communication on mobile devices.
Type Flexibility and Conversion
The Android implementation (written in Kotlin) handles parameter mismatches gracefully by supporting both String and Numeric values for enums like DataBits and StopBits. This prevents failures when data types vary between the Rust mobile bridge and the Kotlin implementation.
Sources: debug.md:5-12, debug.md:65-80
Common Error Scenarios
Based on integration tests, the following common errors are handled across the system:
| Error String | Cause | Recovery Action |
|---|---|---|
Port not found | Physical cable unplugged or wrong path. | Re-scan using available_ports(). |
Permission denied | OS-level locking or lack of USB permissions. | Request permissions or close competing apps. |
Device busy | Port is already in use by another process. | Close the other process or use forceClose(). |
Operation timed out | Backend failed to read/write within timeout limit. | Increase timeout or check baud rate. |
Sources: tests/error-handling.test.ts:20-60, debug.md:120-135
Reconnection Logic
The system includes an auto-reconnect feature to handle physical disconnections. When a disconnected event is received from the backend, the frontend API can trigger a sequence of reconnection attempts.
Conclusion
Error handling in the tauri-plugin-serialplugin is a multi-layered system. It combines Rust's strict type safety for backend logic, Kotlin's robust logging for mobile debugging, and JavaScript's validation and event-driven architecture for a seamless developer experience. By categorizing errors into hardware, library, and logic variants, the plugin ensures that failure states are actionable and descriptive.
Sources: src/lib.rs, debug.md:150-160