Error Handling

Core Question

Is this failure expected or a bug?

This single question drives every error handling decision:

• Expected (file not found, invalid input, network timeout) → Result<T, E>
• Absence (optional value, lookup miss) → Option<T>
• Bug (violated invariant, impossible state) → panic! / expect()

If you're unsure, it's almost certainly expected — use Result.

Error → Design Question

Quick Decisions

The ? Operator

? is the backbone of Rust error handling. It propagates errors up the call stack, converting types via From automatically.

fn load_config(path: &Path) -> Result<Config, AppError> {
    let content = std::fs::read_to_string(path)?;  // io::Error → AppError via From
    let config: Config = toml::from_str(&content)?; // toml::Error → AppError via From
    Ok(config)
}

Add context when the error alone doesn't tell the story:

use anyhow::Context;

let content = std::fs::read_to_string(path)
    .with_context(|| format!("failed to read config from {}", path.display()))?;

Library vs Application

Library Error (thiserror)

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ParseError {
    #[error("invalid syntax at line {line}: {message}")]
    Syntax { line: usize, message: String },

    #[error("unexpected end of file")]
    UnexpectedEof,

    #[error("io error reading input")]
    Io(#[from] std::io::Error),
}

Application Error (anyhow)

use anyhow::{Context, Result, bail, ensure};

fn run() -> Result<()> {
    let config = load_config("app.toml")
        .context("failed to initialize")?;

    ensure!(config.port > 0, "port must be positive, got {}", config.port);

    if config.debug && config.production {
        bail!("cannot enable debug in production");
    }
    Ok(())
}

Error Message Conventions

• Start lowercase, no trailing punctuation: "invalid input" not "Invalid input."
• Acronyms and error codes stay uppercase: "DNS lookup failed", "HTTP 503"
• Context reads naturally when chained: "failed to load config: invalid toml: expected '=' at line 3"

Usage Scenarios

Scenario 1: "I'm writing a library — how should I define errors?" → Use thiserror. Create an enum with one variant per failure mode the caller cares about. Use #[from] for automatic conversion from underlying errors. Don't expose internal error types — wrap them.

Scenario 2: "I have unwrap() calls everywhere in my application" → Replace with ? and anyhow::Result. Add .context() where the error alone isn't enough to diagnose the problem. Keep unwrap() only in tests and for invariants you've already validated.

Scenario 3: "Should I use expect or return an error here?" → If the caller can do something about it (retry, use a default, report to user), return Result. If it means the program's logic is broken (invariant violation), expect("reason this should never fail") is appropriate.

Reference Files

Cross-References