Simplifying Rust Error Handling with Thiserror

Error Handling In programming, error handling is a crucial part. In Rust, we often use the Result and Option types for error handling. However, sometimes we need to create custom error types. This is where the thiserror crate comes into play, significantly simplifying the code. At the end of the article, there is a comparison between using thiserror and not using it. Overview of the thiserror Crate The main goal of the thiserror crate is to simplify the creation and handling of custom errors in Rust. To use thiserror in your project, first add it to your Cargo.toml: [dependencies] thiserror = "1.0" Creating Custom Errors The thiserror crate, by combining Rust's derive macros and custom attributes, provides developers with the ability to quickly create custom error types. Example: use thiserror::Error; // Definition of a custom error type #[derive(Error, Debug)] pub enum MyError { // Description for DataNotFound error #[error("data not found")] DataNotFound, // Description for InvalidInput error #[error("invalid input")] InvalidInput, } // Example function showing how to use custom errors fn search_data(query: &str) -> Result { if query.is_empty() { // Return InvalidInput error when the query is empty return Err(MyError::InvalidInput); } // The actual data query logic is omitted here // ... // Return DataNotFound error when data is not found Err(MyError::DataNotFound) } Here, MyError is the custom error enum we defined. Each variable is annotated with an #[error("...")] attribute that provides the message to be displayed when the error is triggered. Nested Errors Error chaining allows capturing and responding to errors propagated from underlying libraries or functions. thiserror provides a way to specify that an error is caused by another error. Example: use std::io; use thiserror::Error; // Definition of a custom error type #[derive(Error, Debug)] pub enum MyError { // Description for IoError, which contains a nested io::Error #[error("I/O error occurred")] IoError(#[from] io::Error), } // Example function showing how to use nested errors fn read_file(file_path: &str) -> Result { // If fs::read_to_string returns an error, we use MyError::from to convert it into MyError::IoError std::fs::read_to_string(file_path).map_err(MyError::from) } The #[from] attribute indicates that an io::Error can be automatically converted into MyError::IoError. Dynamic Error Messages Dynamic error messages allow generating error messages based on runtime data. Example: use thiserror::Error; // Definition of a custom error type #[derive(Error, Debug)] pub enum MyError { // Description for FailedWithCode, where {0} will be dynamically replaced with the actual code value #[error("failed with code: {0}")] FailedWithCode(i32), } // Example function showing how to use dynamic error messages fn process_data(data: &str) -> Result { let error_code = 404; // Some computed error code // Use the dynamic error_code to create a FailedWithCode error Err(MyError::FailedWithCode(error_code)) } Cross-Library and Cross-Module Error Handling thiserror also supports automatic conversion from other error types. This is particularly useful for error handling across modules or libraries. Example: use thiserror::Error; // Simulated error type imported from another library #[derive(Debug, Clone)] pub struct OtherLibError; // Definition of a custom error type #[derive(Error, Debug)] pub enum MyError { // Description for OtherError, which directly inherits from its inner error type #[error(transparent)] OtherError(#[from] OtherLibError), } // Example function showing how to convert from another error type fn interface_with_other_lib() -> Result { // Call a function from another library... // If that function returns an error, we use MyError::from to convert it into MyError::OtherError Err(MyError::from(OtherLibError)) } The #[error(transparent)] attribute means that this error simply acts as a container for another error, and its error message will be directly inherited from its "source" error. Comparison with Other Error Handling Crates Although thiserror is very useful, it is not the only error handling crate available. For example, anyhow is another popular crate used for rapid prototyping and application development. However, thiserror provides more flexible error definitions and pattern matching capabilities. Practical Case Consider an operation involving reading and parsing a file. We need to handle potential I/O errors and parsing errors. Example: use std::fs; use thiserror::Error; // Simulated parse error type imported from another part #[derive(Debug, Clone)] pub struct ParseDataError; // Definition of a custom error type #[derive(Error, Debug)] pub enum MyError

[dependencies]
thiserror = "1.0"

use thiserror::Error;

// Definition of a custom error type
#[derive(Error, Debug)]
pub enum MyError {
    // Description for DataNotFound error
    #[error("data not found")]
    DataNotFound,
    // Description for InvalidInput error
    #[error("invalid input")]
    InvalidInput,
}

// Example function showing how to use custom errors
fn search_data(query: &str) -> Result<(), MyError> {
    if query.is_empty() {
        // Return InvalidInput error when the query is empty
        return Err(MyError::InvalidInput);
    }
    // The actual data query logic is omitted here
    // ...
    // Return DataNotFound error when data is not found
    Err(MyError::DataNotFound)
}

use std::io;
use thiserror::Error;

// Definition of a custom error type
#[derive(Error, Debug)]
pub enum MyError {
    // Description for IoError, which contains a nested io::Error
    #[error("I/O error occurred")]
    IoError(#[from] io::Error),
}

// Example function showing how to use nested errors
fn read_file(file_path: &str) -> Result<String, MyError> {
    // If fs::read_to_string returns an error, we use MyError::from to convert it into MyError::IoError
    std::fs::read_to_string(file_path).map_err(MyError::from)
}

use thiserror::Error;

// Definition of a custom error type
#[derive(Error, Debug)]
pub enum MyError {
    // Description for FailedWithCode, where {0} will be dynamically replaced with the actual code value
    #[error("failed with code: {0}")]
    FailedWithCode(i32),
}

// Example function showing how to use dynamic error messages
fn process_data(data: &str) -> Result<(), MyError> {
    let error_code = 404; // Some computed error code
    // Use the dynamic error_code to create a FailedWithCode error
    Err(MyError::FailedWithCode(error_code))
}

use thiserror::Error;

// Simulated error type imported from another library
#[derive(Debug, Clone)]
pub struct OtherLibError;

// Definition of a custom error type
#[derive(Error, Debug)]
pub enum MyError {
    // Description for OtherError, which directly inherits from its inner error type
    #[error(transparent)]
    OtherError(#[from] OtherLibError),
}

// Example function showing how to convert from another error type
fn interface_with_other_lib() -> Result<(), MyError> {
    // Call a function from another library...
    // If that function returns an error, we use MyError::from to convert it into MyError::OtherError
    Err(MyError::from(OtherLibError))
}

use std::fs;
use thiserror::Error;

// Simulated parse error type imported from another part
#[derive(Debug, Clone)]
pub struct ParseDataError;

// Definition of a custom error type
#[derive(Error, Debug)]
pub enum MyError {
    // Description for IoError, containing a nested io::Error
    #[error("I/O error occurred")]
    IoError(#[from] io::Error),
    // Description for ParseError, containing a nested ParseDataError
    #[error("failed to parse data")]
    ParseError(#[from] ParseDataError),
}

// Read a file and attempt to parse its contents
fn read_and_parse(filename: &str) -> Result<String, MyError> {
    // Read file contents, may throw an I/O error
    let content = fs::read_to_string(filename)?;
    // Attempt to parse contents, may throw a parse error
    parse_data(&content).map_err(MyError::from)
}

// Simulated data parsing function, which always returns an error here
fn parse_data(content: &str) -> Result<String, ParseDataError> {
    Err(ParseDataError)
}

// Main function demonstrating how to use the above error handling logic
fn main() {
    match read_and_parse("data.txt") {
        Ok(data) => println!("Data: {}", data),
        Err(e) => eprintln!("Error: {}", e),
    }
}

use std::fmt;

#[derive(Debug)]
enum DataFetchError {
    HttpError(u16),
    Timeout,
    InvalidPayload,
}

impl fmt::Display for DataFetchError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::HttpError(code) => write!(f, "HTTP error with code: {}", code),
            Self::Timeout => write!(f, "Data fetching timed out"),
            Self::InvalidPayload => write!(f, "Invalid payload received"),
        }
    }
}

impl std::error::Error for DataFetchError {}

#[derive(Debug)]
enum DatabaseError {
    ConnectionFailed,
    WriteFailed(String),
}

impl fmt::Display for DatabaseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::ConnectionFailed => write!(f, "Failed to connect to database"),
            Self::WriteFailed(reason) => write!(f, "Failed to write to database: {}", reason),
        }
    }
}

impl std::error::Error for DatabaseError {}

use thiserror::Error;

#[derive(Debug, Error)]
enum DataFetchError {
    #[error("HTTP error with code: {0}")]
    HttpError(u16),
    #[error("Data fetching timed out")]
    Timeout,
    #[error("Invalid payload received")]
    InvalidPayload,
}

#[derive(Debug, Error)]
enum DatabaseError {
    #[error("Failed to connect to database")]
    ConnectionFailed,
    #[error("Failed to write to database: {0}")]
    WriteFailed(String),
}

Related Posts

Should code reviewers reproduce the problem/solution as...

Apr 24, 2025  0

The Coffee-Cam: How Our Office Coffee Machine Learned t...

Apr 25, 2025  0

Must-Read Books for Developers

Apr 23, 2025  0