Error Reporting

Present actionable errors to CLI users with anyhow and miette.

Recipe

use anyhow::Context;
 
fn read_config(path: &str) -> anyhow::Result<String> {
    std::fs::read_to_string(path)
        .with_context(|| format!("failed to read config at {path}"))
}
 
fn main() -> anyhow::Result<()> {
    let cfg = read_config("app.toml")?;
    println!("loaded {cfg}");
    Ok(())
}

When to reach for this: Application binaries where users need context-rich messages, not library-style typed errors.

Working Example

use miette::{miette, IntoDiagnostic, Result};
 
#[derive(Debug, thiserror::Error, Diagnostic)]
#[error("invalid port: {0}")]
#[diagnostic(code(app::invalid_port))]
struct InvalidPort(u16);
 
fn parse_port(s: &str) -> Result<u16> {
    let port: u16 = s.parse().into_diagnostic()?;
    if port == 0 {
        return Err(miette!(InvalidPort(port)));
    }
    Ok(port)
}
 
fn main() -> Result<()> {
    let port = parse_port("0")?;
    println!("listening on {port}");
    Ok(())
}

What this demonstrates:

• anyhow::Context adds location context to std errors
• miette provides diagnostic codes and formatted reports
• thiserror defines small domain error types
• main returns Result for automatic non-zero exit

Deep Dive

anyhow vs thiserror vs miette

CLI Error Guidelines

• One problem per error message
• Say what failed, why, and how to fix it
• Print to stderr; never mix errors into stdout JSON
• Chain context as you cross subsystem boundaries

Exit Codes

use std::process::ExitCode;
 
fn main() -> ExitCode {
    if let Err(e) = run() {
        eprintln!("{e:#}");
        return ExitCode::FAILURE;
    }
    ExitCode::SUCCESS
}

Use {:#} for the full anyhow chain.

Gotchas

• Printing Display only - Users miss the error chain. Fix: Use {:#} or miette::Report.
• Panics in CLI - Ugly stack traces for users. Fix: Return Result and reserve panics for bugs.
• Library uses anyhow - Callers cannot match error types. Fix: Libraries use thiserror; binaries wrap with anyhow.
• Verbose RUST_BACKTRACE by default - Overwhelms users. Fix: Show backtrace only with --verbose or env hint.
• Leaking internal paths - /home/ci/... confuses users. Fix: Strip or relativize paths in user messages.

Alternatives

FAQs

Related

• CLI Basics - exit codes
• clap - validation errors
• Configuration & Env - config load failures
• CLI Best Practices - actionable messages

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.