The Error traitConcept

Explanation

std::error::Error (now core::error::Error, stabilized there since Rust 1.81) is the standard interface an error type is expected to implement. Its requirements are small: a type must already implement Display (a human-readable message) and Debug (a developer-facing representation), and the trait itself adds exactly one method with a default implementation — source(), returning Option<&(dyn Error + 'static)>, the underlying cause this error wrapped, if any. That's the entire contract; the trait carries no data of its own.

It exists so that generic, error-agnostic code can exist at all. Without a shared trait, a top-level main, a logging layer, or an application's error-reporting boundary would need to know the concrete error type of every fallible call it might ever see — completely impractical once a program depends on more than a handful of crates. Implementing Error is what lets an error be boxed into Box<dyn Error>, logged uniformly, and chased back through source() to its root cause, regardless of which crate defined it.

The mental model is a chain, not a single value: many failures are really "this failed, because that failed, because the thing under that failed." source() is how a custom error type exposes the next link down without collapsing the whole chain into one string up front — a caller (or a reporting tool) can walk source() repeatedly until it returns None, printing or inspecting each cause in turn.

Custom error types covers designing an error enum's variants and data; this page is about the trait those types implement to interoperate with the rest of the ecosystem. thiserror's derive generates an Error impl (and often From conversions) from attributes, but it's still worth seeing the manual version at least once — the examples below implement Error by hand, including a manual source() and a manual From impl, so the derive's shorthand has a concrete mechanism behind it rather than being magic.

A function boundary that doesn't want to commit to one concrete error type at all can return Result<T, Box<dyn Error>> (or Box<dyn Error + Send + Sync> when the box must cross threads), since any type implementing Error can be boxed into it, and ? converts into that box automatically — the same mechanism anyhow::Error builds a more ergonomic wrapper around for application code.

Basic usage example

use std::fmt;

#[derive(Debug)]
struct EmptyQueueError;

impl fmt::Display for EmptyQueueError { // <- Error requires Display for a human-readable message
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "cannot dequeue: the queue is empty")
    }
}

impl std::error::Error for EmptyQueueError {} // <- the trait itself: no methods required beyond its supertraits here

Best practices & deeper information

use std::fmt;
use std::error::Error;

#[derive(Debug)]
struct QueryError {
    query: String,
    cause: std::io::Error,
}

impl fmt::Display for QueryError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "query failed: {}", self.query)
    }
}

impl Error for QueryError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.cause) // <- exposes the underlying io::Error as the chained cause
    }
}

fn log_chain(err: &dyn Error) {
    eprintln!("{err}");
    let mut cause = err.source();
    while let Some(inner) = cause {
        eprintln!("caused by: {inner}");
        cause = inner.source();
    }
}

use std::error::Error;

fn load_and_parse(path: &str) -> Result<u32, Box<dyn Error>> {
    // <- `Box<dyn Error>`: accepts any concrete error type behind one boundary
    let contents = std::fs::read_to_string(path)?; // io::Error boxes automatically
    let value: u32 = contents.trim().parse()?; // ParseIntError boxes automatically too
    Ok(value)
}

use std::fmt;
use std::error::Error;

#[derive(Debug)]
enum CacheError {
    Backend(std::io::Error),
}

impl fmt::Display for CacheError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            CacheError::Backend(e) => write!(f, "cache backend failed: {e}"),
        }
    }
}

impl Error for CacheError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            CacheError::Backend(e) => Some(e),
        }
    }
}

impl From<std::io::Error> for CacheError { // <- written by hand, no #[from] derive involved
    fn from(e: std::io::Error) -> Self {
        CacheError::Backend(e)
    }
}

fn read_cache_entry(path: &str) -> Result<String, CacheError> {
    Ok(std::fs::read_to_string(path)?) // <- `?` uses the hand-written `From` impl above
}