Rust Error Handling: Custom Errors, thiserror, and anyhow

In our previous explorations of Result<T, E> and Option<T>, we used .unwrap() and .expect() heavily. Those methods are incredibly useful for rapid prototyping, but they are catastrophic in production. Calling .unwrap() on an Err variant triggers a panic!, immediately terminating the application.

Professional systems architecture demands that errors are gracefully intercepted, logged, and either mitigated or explicitly surfaced to the user.

In this module, we dissect exact mechanisms for defining custom Domain Errors, implementing the standard Error trait, and streamlining error propagation cleanly using the two most famous libraries in the Rust ecosystem: thiserror and anyhow.

1. Defining Custom Error Types

Imagine you are building a banking API. When a transaction fails, returning a standard string (Err("Insufficient funds")) is terrible practice. Calling code cannot mathematically match against raw strings to determine logic flow securely.

You should define your Errors strongly using Enums!

#[derive(Debug)]
pub enum TransactionError {
    InsufficientFunds(f64), // We can embed the exact deficit amount!
    AccountLocked,
    RateLimitExceeded,
}

pub fn execute_transfer(amount: f64) -> Result<(), TransactionError> {
    let balance = 100.0;
    
    if amount > balance {
        return Err(TransactionError::InsufficientFunds(amount - balance));
    }
    
    // Process transfer...
    Ok(())
}

Now, the calling function can cleanly execute a match expression, routing logic perfectly based strictly on the type of error thrown.

2. The std::error::Error Trait

While defining a custom enum is great for internal business logic, the greater Rust ecosystem has no idea how to interact with TransactionError. If you use libraries like Hyper or Tokio, they expect errors sent backward up the stack to conform to the standard std::error::Error trait.

To officially integrate into the ecosystem, your custom error must implement two preceding traits: Debug and Display.

use std::fmt;
use std::error::Error;

// 1. Must derive Debug
#[derive(Debug)]
pub enum DatabaseError {
    ConnectionTimeout,
    InvalidQuery,
}

// 2. Must physically implement Display (How does it print to a screen for humans?)
impl fmt::Display for DatabaseError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            DatabaseError::ConnectionTimeout => write!(f, "The database failed to respond in time."),
            DatabaseError::InvalidQuery => write!(f, "The SQL query syntax was rejected."),
        }
    }
}

// 3. Implement the Error trait (Usually requires nothing inside it!)
impl Error for DatabaseError {}

Writing this structural boilerplate manually for twenty different Domain Errors across a giant microservice is incredibly tedious.

Enter the thiserror crate.

3. Libraries for Libraries: The thiserror Crate

If you are writing a reusable library (a "crate") that other developers will download from crates.io, you should absolutely use the thiserror package.

It uses Procedural Macros to automatically generate the Display, Debug, and Error trait implementations seamlessly.

# Cargo.toml
[dependencies]
thiserror = "1.0"

use thiserror::Error;

#[derive(Error, Debug)]
pub enum DataStoreError {
    #[error("Internal disconnect: Connection lost")]
    Disconnect,
    
    // We can map embedded variables dynamically directly into the Error String!
    #[error("Failed to parse the file at path: {0}")]
    ParseError(String),
    
    // We can implicitly convert OTHER errors (like std::io::Error) into OUR error automatically!
    #[error("System IO failure")]
    Io(#[from] std::io::Error),
}

Notice the #[from] attribute! Because of that macro, if an internal standard File::open throws an io::Error, using the ? operator natively converts it instantly into our custom DataStoreError::Io(err) wrap format and sends it up the chain. Zero manual mapping required!

4. Applications and Binaries: The anyhow Crate

If thiserror is specifically for building structured Libraries with rigid boundaries, what do you use when building top-level Applications (like CLIs or Web API executables)?

When writing an Application, you often don't care what precise type of error occurred deep down in a dependency tree. You simply want one single, unified Error type that you securely bubble up to your main loop to print to the console or log to Datadog.

Enter the anyhow crate.

anyhow provides a generic anyhow::Result<T> that transparently catches every possible error type that implements std::error::Error.

use anyhow::{Context, Result};
use std::fs::File;

// The return type is incredibly clean. We don't have to specify an Error Enum at all!
fn read_config() -> Result<String> {
    // If this fails, the error natively translates into an anhyow::Error.
    
    // We also use .context() to add human-readable breadcrumbs 
    // to the error chain BEFORE it propagates upwards!
    let mut file = File::open("config.json")
        .context("Failed to open the critical configuration JSON file")?;
        
    Ok(String::from("Successfully loaded config"))
}

fn main() {
    match read_config() {
        Ok(_) => println!("Boot complete"),
        Err(e) => {
            // Because we used anyhow, we get automatic stack-trace printing!
            println!("Application Crash: {:?}", e);
        }
    }
}

If the File::open command failed, the output of {:?} would read:

Application Crash: Failed to open the critical configuration JSON file

Caused by:
    No such file or directory (os error 2)

Summary and Next Steps

Robust software must anticipate failure gracefully. By designing localized system errors via explicit Enums, and leveraging the ? operator for propagation, your code architectures remain flat and readable. The thiserror and anyhow crates form an absolute industry-standard duo that separates strict lower-level library contracts from generalized application-level formatting logic.

With Error Handling complete, you have mastered all the low-level systems programming concepts.

The next step is elevating to architectural scale—writing Software that writes Software. In the next phase, Advanced Rust, we transition entirely to Metaprogramming, evaluating raw asynchronous task execution and Procedural Macros!

Read next: Rust Async/Await: Asynchronous Programming with Tokio →

Quick Knowledge Check

Why is it widely considered an industry anti-pattern to use the 'anyhow' crate when developing a foundational Library package intended for others to download from crates.io?

1. Anyhow forces an overarching MIT License on the entire dependency graph, violating standard Enterprise guidelines.
2. Anyhow relies on the nightly-only experimental features which corrupt compiler compatibility guarantees.
3. Anyhow squashes everything into a generic Error. If a developer uses your library, they cannot easily 'match' against the error to write conditional fallback logic (like retrying specifically upon a Timeout). ✓
4. Anyhow performs a deep-clone on every propagating frame, resulting in unacceptable Memory Heap bloat spanning millions of cycles.

Explanation: When building a library for others to use, you must provide strictly typed Custom Enums (via 'thiserror'). This allows the downstream developer to write match error \{ Timeout => retry(), Invalid => skip() \}. If you use 'anyhow', you destroy that typed structural capability, forcing them to parse the literal text of the String to guess what happened.