Advanced error handling

fn find(id: u32) -> Result<String, String> {
    if id == 0 {
        return Err("not found".to_string());
    }
    Ok("Ada".into())
}

// The caller has to compare texts to react:
match find(0) {
    Err(e) if e == "not found" => { /* fragile: a typo breaks the test */ }
    _ => {}
}

#[derive(Debug)]
enum RepoError {
    Database(sea_orm::DbErr),
    NotFound(i32),
}

impl std::fmt::Display for RepoError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Database(_) => write!(f, "database error"),
            Self::NotFound(id) => write!(f, "item {id} not found"),
        }
    }
}

impl std::error::Error for RepoError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Database(e) => Some(e),
            Self::NotFound(_) => None,
        }
    }
}

impl From<sea_orm::DbErr> for RepoError {
    fn from(e: sea_orm::DbErr) -> Self { Self::Database(e) }
}

About thirty lines for two variants, to maintain by hand with every addition. This is what thiserror generates.

[dependencies]
thiserror = "2"

use thiserror::Error;

#[derive(Debug, Error)]
enum RepoError {
    #[error("database error")]
    Database(#[from] sea_orm::DbErr),

    #[error("item {0} not found")]
    NotFound(i32),
}

#[derive(Debug, thiserror::Error)]
enum FormError {
    #[error("the field is required")]                            // fixed text
    Empty,

    #[error("value {0} out of range")]                           // tuple field by position
    OutOfRange(i64),

    #[error("{field}: {length} characters, maximum {max}")]      // named fields
    TooLong { field: String, length: usize, max: usize },

    #[error("invalid value: {0:?}")]                             // with Debug
    Invalid(String),

    #[error("{}", .0.to_uppercase())]                            // expression on a field
    Raw(String),
}

You can also put #[error] on a struct:

#[derive(Debug, thiserror::Error)]
#[error("quota exceeded: {used}/{limit}")]
struct Quota { used: u32, limit: u32 }

#[derive(Debug, thiserror::Error)]
enum ImportError {
    #[error("cannot read the file")]
    Read(#[from] std::io::Error),

    #[error("malformed line")]
    Format(#[from] std::num::ParseIntError),
}

fn import(path: &str) -> Result<Vec<i64>, ImportError> {
    let text = std::fs::read_to_string(path)?;          // io::Error -> Read
    let v = text.lines().map(|l| l.parse::<i64>()).collect::<Result<_, _>>()?;   // -> Format
    Ok(v)
}

#[from] generates impl From<std::io::Error> for ImportError and declares the field as the source. Only one variant per source type: two #[from] std::io::Error variants would be ambiguous.

#[derive(Debug, thiserror::Error)]
enum ConfigError {
    #[error("reading {path}")]
    Read {
        path: String,
        #[source]
        cause: std::io::Error,
    },
}

fn read(path: &str) -> Result<String, ConfigError> {
    std::fs::read_to_string(path).map_err(|cause| ConfigError::Read {
        path: path.to_string(),
        cause,
    })
}

What it is for: when the variant needs other data than the cause (here the path), #[from] cannot guess it. A field named source is taken as the cause automatically, without an attribute.

#[derive(Debug, thiserror::Error)]
enum ApiError {
    #[error("resource not found")]
    NotFound,

    #[error(transparent)]
    Other(#[from] anyhow::Error),      // Display and source are those of the wrapped error
}

What it is for: a "everything else" variant that adds no message, or an opaque public type that hides the internal error:

#[derive(Debug, thiserror::Error)]
#[error(transparent)]
pub struct MyError(#[from] InternalError);    // the internal enum can change without breaking the API

#[derive(Debug, thiserror::Error)]
enum InternalError {
    #[error("x")]
    X,
}

[dependencies]
anyhow = "1"

use anyhow::Result;            // Result<T, anyhow::Error>

fn load_port() -> Result<u16> {
    let t = std::fs::read_to_string("port.txt")?;    // any Error + Send + Sync error
    let p = t.trim().parse::<u16>()?;
    Ok(p)
}

fn main() -> Result<()> {
    let port = load_port()?;
    println!("{port}");
    Ok(())
}

anyhow::Error accepts any error that implements std::error::Error + Send + Sync + 'static. It keeps the original cause, a call stack if RUST_BACKTRACE=1, and the context added along the way.

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

fn check_age(age: i32) -> Result<u32> {
    // anyhow!: build an error
    if age < 0 {
        return Err(anyhow!("negative age: {age}"));
    }

    // bail!: build AND return (same as return Err(anyhow!(..)))
    if age > 150 {
        bail!("unlikely age: {age}");
    }

    // ensure!: return an error if the condition is false
    ensure!(age >= 18, "must be an adult (age: {age})");

    Ok(age as u32)
}

The three forms give the same error; bail! and ensure! are shorter for checks at the start of a function.

use anyhow::{Context, Result};

fn read_config() -> Result<String> {
    std::fs::read_to_string("config.toml").context("reading the configuration")
}
// Display: reading the configuration
// Cause: No such file or directory (os error 2)

The Context trait adds .context() and .with_context() to any Result whose error implements Error, and also to Option (a None becomes an error).

fn read(path: &str) -> Result<String> {
    std::fs::read_to_string(path).with_context(|| format!("reading {path}"))
}

context(format!(...)) would build the String on every call, even on success; with_context only calls it on error.

use std::collections::HashMap;

fn port(env: &HashMap<String, String>) -> Result<u16> {
    let text = env.get("PORT").context("PORT variable missing")?;   // None -> error
    text.parse().with_context(|| format!("invalid PORT: {text}"))
}

fn read_users() -> Result<Vec<String>> {
    let t = std::fs::read_to_string("users.csv").context("opening users.csv")?;
    Ok(t.lines().map(String::from).collect())
}

fn start() -> Result<()> {
    let u = read_users().context("loading accounts at startup")?;
    println!("{} accounts", u.len());
    Ok(())
}
// Error: loading accounts at startup
//
// Caused by:
//     0: opening users.csv
//     1: No such file or directory (os error 2)

Each layer says what it was trying to do; the original cause stays at the end of the chain.

fn show(e: &anyhow::Error) {
    println!("{e}");        // only the last context
    println!("{e:#}");      // the whole chain on one line: a: b: c
    println!("{e:?}");      // full chain on several lines + backtrace if enabled
}

Use {e:#} in one-line logs, {e:?} for the terminal or a bug report.

fn causes(e: &anyhow::Error) {
    for (i, cause) in e.chain().enumerate() {
        println!("{i}: {cause}");
    }
    let root = e.root_cause();
}

fn react(e: &anyhow::Error) {
    if let Some(io) = e.downcast_ref::<std::io::Error>() {
        if io.kind() == std::io::ErrorKind::NotFound {
            println!("file missing");
        }
    }
}

downcast_ref looks for the type in the whole chain, context included. If you often need to downcast, it is a sign that a typed error (thiserror) would fit better at that spot.

// A library exposes typed errors
#[derive(Debug, thiserror::Error)]
pub enum PaymentError {
    #[error("card declined")]
    Declined,
    #[error("service unavailable")]
    Unavailable(#[source] std::io::Error),
}

// The application receives them with anyhow: the conversion is automatic
fn pay() -> anyhow::Result<()> {
    charge().context("payment of order 42")?;
    Ok(())
}

fn charge() -> Result<(), PaymentError> { Err(PaymentError::Declined) }

// ... and can still react to the specific case
fn handle() {
    if let Err(e) = pay() {
        if let Some(PaymentError::Declined) = e.downcast_ref::<PaymentError>() {
            println!("offer another payment method");
        }
    }
}

#[derive(Debug, thiserror::Error)]
pub enum RepoError {
    #[error("article {0} not found")]
    NotFound(i32),
    #[error("database error")]
    Database(#[from] sea_orm::DbErr),
}

#[derive(Debug, thiserror::Error)]
pub enum ArticleError {
    #[error("empty title")]
    EmptyTitle,
    #[error("you are not the author of this article")]
    NotAuthor,
    #[error(transparent)]
    Repo(#[from] RepoError),
}

pub async fn publish(id: i32, author: i32) -> Result<(), ArticleError> {
    let article = load(id).await?;            // RepoError -> ArticleError::Repo
    if article.author != author {
        return Err(ArticleError::NotAuthor);
    }
    Ok(())
}

struct Article { author: i32 }
async fn load(id: i32) -> Result<Article, RepoError> { Err(RepoError::NotFound(id)) }

fn status(e: &ArticleError) -> u16 {
    match e {
        ArticleError::EmptyTitle => 400,
        ArticleError::NotAuthor => 403,
        ArticleError::Repo(RepoError::NotFound(_)) => 404,
        ArticleError::Repo(RepoError::Database(_)) => 500,
    }
}

The match is exhaustive: adding a variant forces you to decide its HTTP code.

use runique::prelude::*;

pub async fn article_detail(request: Request) -> AppResult<Response> {
    let id = request.get_path_as::<Pk>("id").unwrap_or_default();
    let Some(article) = article::Entity::find_by_id(id)
        .one(request.db())
        .await?                                      // DbErr -> 500 automatically
    else {
        return Err(Box::new(AppError::new(ErrorContext::not_found(&format!("/articles/{id}")))));
    };
    // ...
}

Constructors available on ErrorContext: not_found(path), bad_request(message), database(error), from_anyhow(&error), generic(StatusCode, message).

use runique::prelude::*;

impl From<ArticleError> for Box<AppError> {
    fn from(e: ArticleError) -> Self {
        let context = match &e {
            ArticleError::EmptyTitle => ErrorContext::bad_request("The title is required."),
            ArticleError::NotAuthor => {
                ErrorContext::generic(StatusCode::FORBIDDEN, "Action reserved for the author.")
            }
            ArticleError::Repo(RepoError::NotFound(id)) => {
                ErrorContext::not_found(&format!("/articles/{id}"))
            }
            ArticleError::Repo(RepoError::Database(db)) => ErrorContext::database(db),
        };
        Box::new(AppError::new(context))
    }
}

pub async fn publish_article(request: Request) -> AppResult<Response> {
    let id = request.get_path_as::<i32>("id").unwrap_or_default();
    publish(id, 1).await?;              // ArticleError -> Box<AppError> thanks to the From
    // ...
}

From<ArticleError> for Box<AppError> is allowed in your crate because ArticleError belongs to you (orphan rule, see traits-avances).

use anyhow::Context;

pub async fn create_article(
    title: String,
    content: String,
    db: &DatabaseConnection,
) -> anyhow::Result<article::Model> {
    let active = article::ActiveModel {
        title: Set(title.trim().to_string()),
        content: Set(content),
        ..Default::default()
    };
    active
        .insert(db)
        .await
        .with_context(|| format!("inserting the article \"{}\"", title.trim()))
}

The handler calls create_article(...).await?: the anyhow::Error becomes a 500 thanks to the conversions of section 9.2, with the whole context chain in the logs.

#[derive(Debug, thiserror::Error)]
enum LoginError {
    #[error("invalid credentials")]     // same message for both cases
    UnknownUser,
    #[error("invalid credentials")]
    WrongPassword,
}
// The two variants stay distinct for logs and tests.

use serde::Deserialize;

#[derive(Deserialize)]
struct Settings { port: u16 }

// 1. Box<dyn Error>: simple, no context
fn load_v1(path: &str) -> Result<Settings, Box<dyn std::error::Error>> {
    let t = std::fs::read_to_string(path)?;
    Ok(serde_json::from_str(&t)?)
}

// 2. anyhow + context: for an application
fn load_v2(path: &str) -> anyhow::Result<Settings> {
    use anyhow::Context;
    let t = std::fs::read_to_string(path).with_context(|| format!("reading {path}"))?;
    serde_json::from_str(&t).with_context(|| format!("format of {path}"))
}

// 3. thiserror: for a library, the caller tells the cases apart
#[derive(Debug, thiserror::Error)]
enum SettingsError {
    #[error("reading {path}")]
    Read { path: String, #[source] cause: std::io::Error },
    #[error("format of {path}")]
    Format { path: String, #[source] cause: serde_json::Error },
}

fn load_v3(path: &str) -> Result<Settings, SettingsError> {
    let t = std::fs::read_to_string(path).map_err(|cause| SettingsError::Read {
        path: path.into(),
        cause,
    })?;
    serde_json::from_str(&t).map_err(|cause| SettingsError::Format {
        path: path.into(),
        cause,
    })
}

// thiserror
#[derive(Debug, thiserror::Error)]
enum E {
    #[error("text {0}")]             A(i32),
    #[error("{field}")]              B { field: String },
    #[error("cause")]                C(#[from] std::io::Error),
    #[error("x")]                    D { #[source] cause: std::io::Error },
    #[error(transparent)]            F(#[from] anyhow::Error),
}

// anyhow
use anyhow::{anyhow, bail, ensure, Context, Result};
fn f() -> Result<()> {
    let v = op().context("step")?;
    let w = op().with_context(|| format!("step {v}"))?;
    let x = option.context("missing")?;
    ensure!(cond, "message {v}");
    bail!("message");
}
format!("{e}")  format!("{e:#}")  format!("{e:?}")  e.chain()  e.downcast_ref::<T>()

// Runique
AppResult<Response>                       // Result<Response, Box<AppError>>
Err(Box::new(AppError::new(ErrorContext::not_found(path))))
ErrorContext::bad_request(msg)   ErrorContext::generic(StatusCode::FORBIDDEN, msg)
impl From<MyError> for Box<AppError> { .. }