Custom error types

Why not just use String errors?

Result<T, String> is easy, but the caller only gets text. It cannot tell "file missing" (maybe create it) from "bad number on line 7" (show the line to the user) without searching inside the message, which is fragile. A custom error type gives each kind of failure its own variant, so callers can match on it.

#[derive(Debug)]
enum OrderError {
    NotFound(u32),                 // order id
    OutOfStock { item: String },
    PaymentFailed(String),         // reason from the gateway
}

Display: the human message

Errors should print well. Implement the Display trait so {} works. Traits are covered in module 7; for now, copy the pattern: write a fmt function that uses write! to produce the message.

use std::fmt;

impl fmt::Display for OrderError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            OrderError::NotFound(id) => write!(f, "order {id} not found"),
            OrderError::OutOfStock { item } => write!(f, "{item} is out of stock"),
            OrderError::PaymentFailed(why) => write!(f, "payment failed: {why}"),
        }
    }
}

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

From: letting ? convert errors

Suppose your function returns Result<_, AppError>, and inside it you call parse(), which fails with ParseIntError. The ? operator will convert ParseIntError into AppError automatically if you implement From<ParseIntError> for AppError.

use std::num::ParseIntError;

#[derive(Debug)]
enum AppError {
    BadNumber(ParseIntError),
    Io(std::io::Error),
}

impl From<ParseIntError> for AppError {
    fn from(e: ParseIntError) -> Self {
        AppError::BadNumber(e)
    }
}

impl From<std::io::Error> for AppError {
    fn from(e: std::io::Error) -> Self {
        AppError::Io(e)
    }
}

fn load_stock(path: &str) -> Result<u32, AppError> {
    let text = std::fs::read_to_string(path)?;   // io::Error -> AppError::Io
    let n = text.trim().parse::<u32>()?;         // ParseIntError -> AppError::BadNumber
    Ok(n)
}

Callers can now react precisely

match load_stock("stock.txt") {
    Ok(n) => println!("{n} in stock"),
    Err(AppError::Io(_)) => println!("stock file missing, starting from 0"),
    Err(AppError::BadNumber(e)) => println!("stock file is corrupt: {e}"),
}

Crates that remove the boilerplate

Writing Display and From by hand is repetitive. Two popular crates (libraries from crates.io) help:

// Cargo.toml: thiserror = "2"
use thiserror::Error;

#[derive(Debug, Error)]
enum OrderError {
    #[error("order {0} not found")]
    NotFound(u32),
    #[error("could not read file")]
    Io(#[from] std::io::Error),
}

A common rule: libraries define precise error enums (often with thiserror) so their users can match on them; applications often use anyhow at the top level, where the goal is mainly to report the problem clearly.

Common mistakes

• One giant error enum for the whole program with 40 variants. Keep error types close to the module that produces them.
• Losing the original error. Keep it inside your variant (BadNumber(ParseIntError)) so the details are not lost.
• Error messages with capital letters and full stops at the end. The Rust convention is short lowercase messages, because they are often joined: "could not load stock: invalid digit found in string".
• Forgetting impl std::error::Error, so your type does not work with Box<dyn Error>.