What thiserror and anyhow actually generate

The code in this article cannot be run on this site. thiserror and anyhow are external crates (packages published on crates.io), and thiserror also contains a procedural macro, which is a program the compiler runs to generate code. The course harness builds one source file with no external crates, so the examples here are for reading. They were checked with thiserror 2.0 and anyhow 1.0 in an ordinary Cargo project.

Both crates package code that you can write with the standard library alone: an impl Display that produces the message, an impl std::error::Error whose source() method returns the underlying cause, From impls that let ? convert one error type into another, and a trait that attaches context to an error. The exercises implementing the Error trait, error chains and source(), From conversions and adding error context build each of those by hand. This article shows which of them each crate provides, so that an attribute such as #[error("...")] reads as ordinary code rather than as something opaque.

thiserror, translated

thiserror provides a derive macro, #[derive(Error)], for your own error types. Here is an enum written with it:

use thiserror::Error;

#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("key `{0}` is missing")]
    MissingKey(String),

    #[error("could not read the config file")]
    Io(#[from] std::io::Error),

    #[error("key `{key}` is not an integer")]
    BadInt {
        key: String,
        #[source]
        source: std::num::ParseIntError,
    },

    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

Each attribute corresponds to part of an impl you could write yourself:

#[derive(Debug)] is still required, because the Error trait has Debug as a supertrait. A variant with #[from] may not have other fields, because From::from receives only the inner error and would have nothing to fill them with. (The one exception is a backtrace field, and thiserror's backtrace support currently needs a nightly compiler.)

Written out by hand, the four variants look like this. The code the macro emits is not character-for-character identical (for example, it calls a few small helper traits from the thiserror crate), but it behaves the same way:

impl std::fmt::Display for ConfigError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ConfigError::MissingKey(k) => write!(f, "key `{k}` is missing"),
            ConfigError::Io(_) => f.write_str("could not read the config file"),
            ConfigError::BadInt { key, .. } => write!(f, "key `{key}` is not an integer"),
            // transparent: forward to the inner error's Display.
            ConfigError::Other(e) => std::fmt::Display::fmt(e, f),
        }
    }
}

impl std::error::Error for ConfigError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            ConfigError::MissingKey(_) => None,
            ConfigError::Io(e) => Some(e),
            ConfigError::BadInt { source, .. } => Some(source),
            // transparent: forward to the inner error's own source().
            ConfigError::Other(e) => e.source(),
        }
    }
}

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

impl From<anyhow::Error> for ConfigError {
    fn from(e: anyhow::Error) -> Self {
        ConfigError::Other(e)
    }
}

Note that the Io message does not include the io::Error text. The cause is reachable through source() instead, and code that prints a whole chain (as shown later for anyhow) prints it there.

thiserror has no runtime machinery of its own: it adds no allocation, global state or background work, and the derived impls are ordinary trait impls. The crate is still a normal dependency that gets compiled, because the generated code refers to those helper traits. Its documentation states that it deliberately does not appear in your public API: callers see the same Display, Error and From impls they would see if you had written them by hand, and switching between hand-written impls and thiserror is not a breaking change. That is why it is commonly used in libraries.

anyhow, translated

anyhow provides one error type for code that mostly needs to report errors rather than match on them:

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

struct Config {
    port: u16,
}

fn load(path: &str) -> Result<Config> {
    let text = std::fs::read_to_string(path)
        .with_context(|| format!("reading config from {path}"))?;

    if text.is_empty() {
        bail!("config file {path} is empty");
    }

    let port: u16 = text.trim().parse().context("parsing port")?;
    Ok(Config { port })
}

Piece by piece:

• anyhow::Error plays the same role as Box<dyn std::error::Error + Send + Sync + 'static>: it can hold any error type that is Send, Sync and 'static, and ? converts such errors into it. It also records context messages and can capture a backtrace. Its representation differs from a Box<dyn Error>: an anyhow::Error is one pointer wide, while a boxed trait object is two (a data pointer and a vtable pointer). An anyhow::Error always allocates; a Box allocates for any error type that is not zero-sized.
• anyhow::Error does not implement std::error::Error itself. It dereferences to dyn Error + Send + Sync, and the #[error(transparent)] variant above is a pattern thiserror documents for holding one.
• anyhow::Result<T> is a type alias: type Result<T, E = anyhow::Error> = std::result::Result<T, E>. The error type defaults to anyhow::Error but can be overridden.
• .context(msg) and .with_context(|| msg) come from the Context extension trait, the same shape as the trait built in the adding-context exercise. anyhow implements it for Result<T, E> (where E is a Send + Sync + 'static error, or an anyhow::Error) and for Option<T>. On an error it returns a new anyhow::Error whose message is msg and whose source() chain leads to the original error. with_context takes a closure that runs only when there is an error, which avoids building the message (for example, with format!) on success. This is the same eager-versus-lazy choice as unwrap_or versus unwrap_or_else.
• anyhow!("...") builds an anyhow::Error from a format string (or from an existing error value), and bail!("...") is equivalent to return Err(anyhow!("...")).
• Formatting. {} prints only the outermost message, such as parsing port. {:#} prints the whole chain on one line joined with ": ", such as parsing port: invalid digit found in string. {:?} prints the outermost message, then a Caused by: list of the chain, then the backtrace if one was captured. Backtraces are captured only when the environment variable RUST_LIB_BACKTRACE=1 or RUST_BACKTRACE=1 is set (and RUST_LIB_BACKTRACE is not 0).
• Downcasting. error.downcast_ref::<std::num::ParseIntError>() still finds the original error after context has been added, and the context value itself can be downcast as well.

Compared with Box<dyn Error + Send + Sync>, then, anyhow adds context wrapping, optional backtrace capture, a one-pointer representation, chain-aware formatting and downcasting through context layers. Each piece is a convenience over a pattern you can write by hand, not a different error-handling model.

Related crates

Some other error-handling crates follow the same patterns:

• snafu generates Display and Error impls like thiserror, and also generates context selectors: small structs used to attach context, so the context fields a variant needs are checked by the compiler.
• eyre is a fork of anyhow whose report format can be customized by installing a handler. color-eyre is such a handler; it prints colored, sectioned reports and supports attaching notes and suggestions.
• miette produces diagnostic reports with source-code snippets, labels and help text, similar in style to rustc's own errors. It is designed for tools that report problems in input text, such as parsers and linters.

The examples in this article were checked against thiserror 2.0 and anyhow 1.0. Major versions can change details, so check the documentation for the version you depend on.

use thiserror::Error;

#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("could not read {path}")]
    Read { path: String, #[source] source: std::io::Error },

    #[error("could not write {path}")]
    Write { path: String, #[source] source: std::io::Error },
}

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

Summary

Both crates generate or wrap the same standard-library pieces that can be written by hand:

• thiserror derives Display, std::error::Error (including source()) and From impls for your own error types, and leaves no trace in your public API.
• anyhow provides a single heap-allocated error type that holds any Send + Sync + 'static error, plus a Context trait for adding messages, chain-aware formatting, downcasting and optional backtraces.

When a compiler error mentions one of these crates, it is usually about one of these impls (a missing Debug, a conflicting From, a field type that does not implement Error, or an error that is not Send), so writing the impl out by hand is a reliable way to understand it.