Mastering Rust Error Handling: 7 Essential Patterns for Robust Code

rust

Mastering Rust Error Handling: 7 Essential Patterns for Robust Code

Learn reliable Rust error handling patterns that improve code quality and maintainability. Discover custom error types, context chains, and type-state patterns for robust applications. Click for practical examples and best practices.

Mar 7, 2025

Mastering Rust Error Handling: 7 Essential Patterns for Robust Code

Error handling is one of Rust’s defining features. The language’s approach to errors emphasizes explicitness and compile-time checks, ensuring that error cases are properly addressed before code reaches production. Through my years of working with Rust, I’ve identified several patterns that have consistently helped create more maintainable and reliable systems.

Custom Error Types

Creating tailored error types for your domain is fundamental to clear error reporting. Custom errors communicate precisely what went wrong and provide appropriate context.

use std::fmt;

#[derive(Debug)]
enum UserServiceError {
    DatabaseError(String),
    ValidationError(String),
    NotFoundError(u64),
    AuthenticationError,
}

impl fmt::Display for UserServiceError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Self::DatabaseError(msg) => write!(f, "Database error: {}", msg),
            Self::ValidationError(msg) => write!(f, "Validation failed: {}", msg),
            Self::NotFoundError(id) => write!(f, "User with ID {} not found", id),
            Self::AuthenticationError => write!(f, "Authentication failed"),
        }
    }
}

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

For more complex applications, the thiserror crate simplifies this pattern:

use thiserror::Error;

#[derive(Error, Debug)]
enum PaymentError {
    #[error("Insufficient funds: available {available}, required {required}")]
    InsufficientFunds { available: u64, required: u64 },
    
    #[error("Payment gateway error: {0}")]
    GatewayError(String),
    
    #[error("Transaction timeout after {0} seconds")]
    Timeout(u32),
}

Result Chaining

Rust’s ? operator, combined with result combinators, creates concise error-handling pipelines. This approach allows you to focus on the happy path while still properly handling errors.

fn process_payment(payment_id: String) -> Result<Transaction, PaymentError> {
    let payment = find_payment(&payment_id)?;
    
    let account = get_account(payment.account_id)
        .map_err(|_| PaymentError::GatewayError("Account retrieval failed".into()))?;
        
    if account.balance < payment.amount {
        return Err(PaymentError::InsufficientFunds { 
            available: account.balance, 
            required: payment.amount 
        });
    }
    
    process_transaction(account, payment)
}

Combining multiple operations becomes straightforward:

fn update_user_profile(user_id: u64, profile: Profile) -> Result<UpdatedUser, ServiceError> {
    let user = find_user(user_id)?;
    let validated_profile = validate_profile(profile)?;
    let updated_user = user.with_profile(validated_profile)?;
    save_user(&updated_user)?;
    Ok(updated_user)
}

Error Context

Adding context to errors helps pinpoint issues in complex applications. The anyhow crate offers excellent tools for this:

use anyhow::{Context, Result};

fn load_configuration() -> Result<Config> {
    let config_path = std::env::var("CONFIG_PATH")
        .context("CONFIG_PATH environment variable not set")?;
        
    let config_text = std::fs::read_to_string(&config_path)
        .context(format!("Failed to read config file at {}", config_path))?;
        
    let config: Config = serde_json::from_str(&config_text)
        .context("Config file contains invalid JSON")?;
        
    Ok(config)
}

For a manual approach without external crates:

fn authenticate_user(credentials: Credentials) -> Result<AuthToken, AuthError> {
    let user = find_user_by_email(&credentials.email)
        .map_err(|e| AuthError::DatabaseError(format!("User lookup failed: {}", e)))?;
        
    if user.is_none() {
        return Err(AuthError::InvalidCredentials("User not found".into()));
    }
    
    let user = user.unwrap();
    if !verify_password(&user.password_hash, &credentials.password) {
        return Err(AuthError::InvalidCredentials("Password incorrect".into()));
    }
    
    generate_auth_token(&user)
}

Error Conversion Traits

Implementing From traits creates seamless error transitions between components:

#[derive(Debug)]
enum ApiError {
    DatabaseError(String),
    ValidationError(String),
    AuthError(String),
    NotFoundError,
    InternalError(String),
}

impl From<DatabaseError> for ApiError {
    fn from(err: DatabaseError) -> Self {
        match err {
            DatabaseError::ConnectionFailed(msg) => Self::DatabaseError(format!("Connection error: {}", msg)),
            DatabaseError::QueryFailed(msg) => Self::DatabaseError(format!("Query error: {}", msg)),
            DatabaseError::RecordNotFound => Self::NotFoundError,
        }
    }
}

impl From<AuthServiceError> for ApiError {
    fn from(err: AuthServiceError) -> Self {
        match err {
            AuthServiceError::InvalidToken => Self::AuthError("Invalid authentication token".into()),
            AuthServiceError::ExpiredToken => Self::AuthError("Authentication token expired".into()),
            AuthServiceError::ServiceDown => Self::InternalError("Authentication service unavailable".into()),
        }
    }
}

fn handle_request(req: Request) -> Result<Response, ApiError> {
    let user = auth_service::validate_token(&req.token)?; // AuthServiceError -> ApiError
    let data = database::fetch_user_data(user.id)?;       // DatabaseError -> ApiError
    
    Ok(Response::new(data))
}

Fallible Iterator Patterns

Handling errors in iterators requires special attention. The collect method on iterators can accumulate Results:

fn process_batch(items: Vec<RawItem>) -> Result<Vec<ProcessedItem>, ProcessingError> {
    items.into_iter()
        .map(|item| {
            let validated = validate_item(&item)?;
            let enriched = enrich_item(validated)?;
            let processed = finalize_item(enriched)?;
            Ok(processed)
        })
        .collect() // Collects into Result<Vec<ProcessedItem>, ProcessingError>
}

For early-exit processing:

fn find_first_valid(candidates: Vec<Candidate>) -> Result<ValidCandidate, ValidationError> {
    for candidate in candidates {
        match validate_candidate(candidate) {
            Ok(valid) => return Ok(valid),
            Err(_) => continue,
        }
    }
    
    Err(ValidationError::NoValidCandidates)
}

For more complex scenarios, fallible iteration patterns help manage resources:

fn process_files(paths: Vec<String>) -> Result<Vec<ProcessedFile>, FileError> {
    let mut processed = Vec::new();
    
    for path in paths {
        let file = match std::fs::File::open(&path) {
            Ok(file) => file,
            Err(e) => {
                log::warn!("Failed to open file {}: {}", path, e);
                continue; // Skip this file but continue processing others
            }
        };
        
        match process_file(file) {
            Ok(result) => processed.push(result),
            Err(e) => return Err(FileError::ProcessingFailed(path, e.to_string())),
        }
    }
    
    if processed.is_empty() {
        return Err(FileError::NoFilesProcessed);
    }
    
    Ok(processed)
}

Type-State Error Handling

Using Rust’s type system to prevent errors at compile time is a powerful pattern I’ve found particularly valuable:

use std::marker::PhantomData;

// State markers
struct Disconnected;
struct Connected;
struct Authenticated;

struct DatabaseClient<State = Disconnected> {
    connection_string: String,
    client: Option<PgClient>,
    _state: PhantomData<State>,
}

impl DatabaseClient<Disconnected> {
    fn new(connection_string: String) -> Self {
        Self {
            connection_string,
            client: None,
            _state: PhantomData,
        }
    }
    
    fn connect(self) -> Result<DatabaseClient<Connected>, ConnectionError> {
        let client = PgClient::connect(&self.connection_string)?;
        
        Ok(DatabaseClient {
            connection_string: self.connection_string,
            client: Some(client),
            _state: PhantomData,
        })
    }
}

impl DatabaseClient<Connected> {
    fn authenticate(self, username: &str, password: &str) -> Result<DatabaseClient<Authenticated>, AuthError> {
        let client = self.client.unwrap();
        client.execute("SELECT authenticate($1, $2)", &[&username, &password])?;
        
        Ok(DatabaseClient {
            connection_string: self.connection_string,
            client: Some(client),
            _state: PhantomData,
        })
    }
}

impl DatabaseClient<Authenticated> {
    fn query<T: FromRow>(&self, query: &str) -> Result<Vec<T>, QueryError> {
        // Only authenticated clients can perform queries
        let client = self.client.as_ref().unwrap();
        // Implementation details...
        Ok(vec![])
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = DatabaseClient::new("postgres://localhost".into())
        .connect()?
        .authenticate("admin", "password")?;
        
    let users = client.query::<User>("SELECT * FROM users")?;
    
    // This would not compile:
    // let disconnected_client = DatabaseClient::new("postgres://localhost".into());
    // disconnected_client.query::<User>("SELECT * FROM users")?;
    
    Ok(())
}

This approach makes it impossible to call operations on objects in an invalid state. The compiler enforces our state transitions.

Local Error Scoping

Containing errors within their relevant components creates cleaner interfaces:

// In database module
mod database {
    pub type Result<T> = std::result::Result<T, Error>;
    
    #[derive(Debug, thiserror::Error)]
    pub enum Error {
        #[error("Connection error: {0}")]
        Connection(String),
        #[error("Query failed: {0}")]
        Query(String),
        #[error("Transaction error: {0}")]
        Transaction(String),
    }
    
    pub fn execute_query(query: &str) -> Result<QueryResult> {
        // Implementation
        Ok(QueryResult {})
    }
}

// In auth module
mod auth {
    pub type Result<T> = std::result::Result<T, Error>;
    
    #[derive(Debug, thiserror::Error)]
    pub enum Error {
        #[error("Invalid credentials")]
        InvalidCredentials,
        #[error("Token expired")]
        TokenExpired,
        #[error("Database error: {0}")]
        Database(#[from] super::database::Error),
    }
    
    pub fn verify_token(token: &str) -> Result<UserId> {
        let result = database::execute_query("SELECT user_id FROM tokens WHERE token = $1")?;
        // More logic...
        Ok(UserId(1))
    }
}

// In service module
mod service {
    pub type Result<T> = std::result::Result<T, Error>;
    
    #[derive(Debug, thiserror::Error)]
    pub enum Error {
        #[error("Authentication error: {0}")]
        Auth(#[from] super::auth::Error),
        #[error("Not found: {0}")]
        NotFound(String),
        #[error("Internal error: {0}")]
        Internal(String),
    }
    
    pub fn get_user_profile(token: &str) -> Result<UserProfile> {
        let user_id = auth::verify_token(token)?;
        // More logic...
        Ok(UserProfile {})
    }
}

Error Reporting

Implementing structured error reporting creates a consistent experience:

fn api_handler(request: Request) -> Response {
    match process_request(request) {
        Ok(result) => Response::ok(result),
        Err(e) => {
            // Log the detailed error
            log::error!("Request processing failed: {:?}", e);
            
            // Increment metrics
            metrics::increment_counter("api.errors", &[("type", e.error_type())]);
            
            // Return appropriate response to client
            match e {
                ApiError::ValidationError(msg) => Response::bad_request(&msg),
                ApiError::AuthError(_) => Response::unauthorized("Authentication required"),
                ApiError::NotFoundError => Response::not_found("Resource not found"),
                ApiError::DatabaseError(_) | ApiError::InternalError(_) => {
                    // Don't expose internal details to client
                    Response::server_error("An internal error occurred")
                }
            }
        }
    }
}

fn process_request(request: Request) -> Result<ApiResponse, ApiError> {
    // Validate the request
    let payload = validate_payload(request.payload)
        .map_err(|e| ApiError::ValidationError(e.to_string()))?;
    
    // Authenticate the user
    let user = authenticate_user(&request.auth_token)
        .map_err(ApiError::AuthError)?;
    
    // Process the request
    let result = perform_operation(user, payload)?;
    
    Ok(ApiResponse::new(result))
}

When working with web frameworks like Actix-Web, you can implement the ResponseError trait:

impl actix_web::ResponseError for ApiError {
    fn error_response(&self) -> HttpResponse {
        match self {
            Self::ValidationError(msg) => HttpResponse::BadRequest().json(ErrorResponse {
                code: "VALIDATION_ERROR",
                message: msg,
            }),
            Self::AuthError(_) => HttpResponse::Unauthorized().json(ErrorResponse {
                code: "UNAUTHORIZED",
                message: "Authentication required",
            }),
            Self::NotFoundError => HttpResponse::NotFound().json(ErrorResponse {
                code: "NOT_FOUND",
                message: "Resource not found",
            }),
            _ => {
                // Log internal errors but don't expose details
                log::error!("Internal server error: {:?}", self);
                HttpResponse::InternalServerError().json(ErrorResponse {
                    code: "INTERNAL_ERROR",
                    message: "An internal error occurred",
                })
            }
        }
    }
}

I’ve found that a well-structured error handling approach not only helps during development but makes production troubleshooting significantly easier. When errors occur, having detailed context, clear categorization, and proper logging means I can identify and fix issues much faster.

Rust’s error handling system is designed to prevent bugs before they happen, and with these patterns, you can leverage the type system to create robust applications that gracefully handle the unexpected. The key is finding the right balance between granularity and simplicity in your error types, ensuring you have enough information to diagnose issues without creating an overly complex error hierarchy.