Library vs Application Error Handling

Choosing the error strategy per crate: who consumes the error decides its shape. Code reacts to errors (match, retry, map to status codes); humans read errors (logs, terminal, bug reports). Libraries serve code, applications serve humans, and services usually need both at once.

#Contents

• 1. The decision
• 2. thiserror in one page
• 3. anyhow in one page
• 4. Using both in one workspace
• 5. Alternatives
• 6. Hand-written errors without any crate
• 7. Migration paths
• 8. Checklist

#1. The decision

Rules of thumb:

• A library never returns anyhow::Error from a public function. The caller cannot distinguish "not found" from "disk full" without downcasting to types you never promised.
• An application gains little from a giant crate-wide enum that only ever gets printed. Use anyhow and spend the effort on context messages.
• A service sits in between: the HTTP layer needs to know "this is a 404", but database and I/O failures are all "500, log it". Typed for what callers react to, anyhow for the rest.

#2. thiserror in one page

[dependencies]
thiserror = "2"

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum FetchError {
    #[error("invalid url {url:?}")]
    InvalidUrl { url: String, #[source] source: url::ParseError },

    #[error("server returned {status} for {url}")]
    Status { url: String, status: u16 },

    #[error("request to {url} timed out after {timeout_ms} ms")]
    Timeout { url: String, timeout_ms: u64 },

    #[error("transport error")]
    Transport(#[from] std::io::Error),
}

What the derive generates:

• impl std::fmt::Display from the #[error(...)] attributes
• impl std::error::Error with source() returning the #[source]/#[from] field (or a field named source)
• impl From<std::io::Error> for FetchError for each #[from]

Nothing else. No runtime, no trait objects, no allocation. The generated code only references std/core traits, so thiserror is not part of your public API: callers never need to depend on it, and you can remove it later by writing the impls by hand without a breaking change.

#3. anyhow in one page

[dependencies]
anyhow = "1"

use anyhow::{Context, Result};

fn main() -> Result<()> {
    let url = std::env::var("FEED_URL").context("FEED_URL is not set")?;
    let body = fetch(&url).with_context(|| format!("fetching feed {url}"))?;
    let items = parse_feed(&body).context("parsing feed XML")?;
    println!("{} items", items.len());
    Ok(())
}

• anyhow::Error holds any E: std::error::Error + Send + Sync + 'static, plus a context chain and an optional backtrace. It is a single pointer wide, so Result<T, anyhow::Error> stays small.
• anyhow::Result<T> is Result<T, anyhow::Error>; the second parameter defaults, so anyhow::Result<T, MyError> also works.
• Context adds a message layer without losing the original: err.downcast_ref::<std::io::Error>() still finds it.
• anyhow::Error itself does not implement std::error::Error (that would conflict with its blanket From<E: Error> impl). It derefs to dyn Error + Send + Sync + 'static, implements AsRef<dyn Error + Send + Sync>, and converts into Box<dyn Error + Send + Sync + 'static>.

#4. Using both in one workspace

workspace/
  crates/store/      library: thiserror StoreError, pub type Result<T, E = StoreError>
  crates/indexer/    library: thiserror IndexError { Store(#[from] StoreError), ... }
  crates/api/        service: thiserror ApiError (typed 4xx) + Internal(#[from] anyhow::Error)
  crates/cli/        binary: anyhow everywhere, main() -> anyhow::Result<()>

The binary keeps the typed information available:

use anyhow::Context;
use store::StoreError;

fn show(id: u64) -> anyhow::Result<()> {
    match store::get(id) {
        Ok(item) => println!("{item}"),
        Err(StoreError::NotFound { .. }) => println!("no item {id}"), // expected case: handled, not an error
        Err(other) => return Err(other).with_context(|| format!("loading item {id}")),
    }
    Ok(())
}

fn exit_code(err: &anyhow::Error) -> u8 {
    // Any layer of the chain can be inspected after context was added.
    if let Some(StoreError::Io(_)) = err.downcast_ref::<StoreError>() { 74 } else { 1 } // 74 = EX_IOERR
}

Library-to-library: wrap the lower error as a variant of the higher one when callers of the higher crate need to react to it; otherwise wrap it as an opaque source with a description of what the higher crate was doing:

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum IndexError {
    #[error("document {doc_id} not found in store")]
    MissingDocument { doc_id: u64 },               // callers react: skip or re-fetch

    #[error("failed to load segment {segment}")]
    Load { segment: u32, #[source] source: store::StoreError }, // callers just report it
}

#5. Alternatives

#snafu (context selectors)

use snafu::{ResultExt, Snafu};
use std::path::PathBuf;

#[derive(Debug, Snafu)]
pub enum ConfigError {
    #[snafu(display("could not read config {}", path.display()))]
    Read { path: PathBuf, source: std::io::Error },

    #[snafu(display("invalid TOML in {}", path.display()))]
    Parse { path: PathBuf, source: toml::de::Error },
}

pub fn load(path: PathBuf) -> Result<String, ConfigError> {
    let text = std::fs::read_to_string(&path).context(ReadSnafu { path: path.clone() })?;
    Ok(text)
}

• Each variant gets a generated "context selector" (ReadSnafu since snafu 0.7) that you pass to .context(..), so the same source type (io::Error) can map to several variants with different context, which is exactly where thiserror's #[from] stops working.
• Also offers ensure!, whatever! and a Whatever type for application-style stringly errors.
• Choose it when nearly every conversion needs context fields; choose thiserror when most are 1:1.

#eyre and color-eyre

use color_eyre::eyre::{Result, WrapErr};

fn main() -> Result<()> {
    color_eyre::install()?;                          // installs panic + error report hooks
    let cfg = std::fs::read_to_string("app.toml").wrap_err("reading app.toml")?;
    run(&cfg)
}

• eyre::Report is an anyhow fork with a pluggable report handler. wrap_err/wrap_err_with are the equivalents of context/with_context; eyre::ContextCompat provides .context() on Option for anyhow-style code.
• color-eyre renders colored reports, optional span traces via tracing-error, and custom sections (.suggestion(..), .note(..) from color_eyre::Section).
• Choose it for developer-facing CLIs. Do not mix anyhow and eyre in the same binary without reason; pick one.

#miette (diagnostics)

use miette::{Diagnostic, NamedSource, SourceSpan};

#[derive(Debug, thiserror::Error, Diagnostic)]
#[error("unknown key `{key}`")]
#[diagnostic(code(config::unknown_key), help("valid keys are: listen, workers, log_level"))]
pub struct UnknownKey {
    key: String,
    #[source_code]
    src: NamedSource<String>,
    #[label("not a recognised key")]
    span: SourceSpan,
}

fn main() -> miette::Result<()> {
    check("app.toml")?;      // fancy report needs miette's "fancy" feature in the binary
    Ok(())
}

• miette builds on thiserror: the error is still a std error; Diagnostic adds code, help, URL, labels and source snippets.
• miette::IntoDiagnostic::into_diagnostic() converts ordinary errors into miette::Report.
• Choose it for compilers, linters, config validators: anything where the user must see where in an input the problem is.

#error-stack

• Report<C> carries a current context type C plus a stack of attachments; at layer boundaries you call .change_context(MyLayerError) and add data with attachment methods. Good for large codebases that want typed contexts and rich attachments; heavier API than thiserror + anyhow. Check the docs of the version you use: attachment method names have changed between releases.

#Comparison

#6. Hand-written errors without any crate

Zero dependencies is a fine choice for small libraries, no_std crates or when compile time matters:

use std::{error::Error, fmt};

#[derive(Debug)]
#[non_exhaustive]
pub enum ParseError {
    Empty,
    BadNumber { line: usize, source: std::num::ParseIntError },
}

impl fmt::Display for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => f.write_str("input is empty"),
            Self::BadNumber { line, .. } => write!(f, "invalid number on line {line}"),
        }
    }
}

impl Error for ParseError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Empty => None,
            Self::BadNumber { source, .. } => Some(source),
        }
    }
}

That is exactly what thiserror would generate for:

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ParseError {
    #[error("input is empty")]
    Empty,
    #[error("invalid number on line {line}")]
    BadNumber { line: usize, #[source] source: std::num::ParseIntError },
}

#7. Migration paths

#Box<dyn Error> everywhere -> structured

1. Make it at least Box<dyn Error + Send + Sync + 'static> (type alias BoxError). Nothing else changes, and async/threads start working.
2. Binaries: replace the alias with anyhow::Result; ? keeps working for every std error. Add context.
3. Libraries: introduce pub enum Error per module, starting with the variants callers already distinguish (search for downcast_ref and to_string().contains( at call sites).

#Result<T, String> -> typed

// before
pub fn parse_port(s: &str) -> Result<u16, String> {
    s.parse().map_err(|e| format!("bad port {s}: {e}"))
}

// after
#[derive(Debug, thiserror::Error)]
#[error("invalid port {input:?}")]
pub struct PortError {
    input: String,
    #[source]
    source: std::num::ParseIntError,
}

pub fn parse_port(s: &str) -> Result<u16, PortError> {
    s.parse().map_err(|source| PortError { input: s.to_owned(), source })
}

#Library returning anyhow -> typed

Keep anyhow internally while you migrate: add a temporary catch-all variant and shrink it over time.

#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    #[error("record {0} not found")]
    NotFound(u64),
    /// Temporary: everything not yet classified. Remove before 1.0.
    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

#[non_exhaustive] lets you split Other into real variants later without a breaking release (callers already have a _ => arm).

#anyhow -> eyre (or back)

Mostly mechanical: anyhow::Result -> eyre::Result, Context::context -> WrapErr::wrap_err, anyhow! -> eyre!, bail!/ensure! exist in both. Install the report hook first thing in main.

#8. Checklist

• Every library crate exposes typed errors; no anyhow in pub fn signatures
• Every binary returns anyhow::Result<()> (or ExitCode) from main
• Error enums are #[non_exhaustive] and Send + Sync + 'static
• No dependency error type you intend to swap is a public field or #[from]
• Services: one ApiError with typed 4xx variants and an Internal catch-all
• Context added on every ? that crosses an I/O or parse boundary in application code