thiserror

thiserror is a lightweight derive macro that implements Rust’s std::error::Error trait for custom error types, eliminating the boilerplate of hand-written Display and source() implementations. Developers annotate an enum or struct with #[derive(Error)] and per-variant #[error(”…”)] messages, and thiserror generates the trait implementations at compile time with no runtime cost and no trace left in the crate’s public API.

Widely regarded as the standard choice for library authors who want precise, structured error types (as opposed to anyhow’s single dynamic error type for application code), thiserror is used throughout the Rust ecosystem by crates that need typed, matchable error enums with readable messages.

What You Get

• A #[derive(Error, Debug)] macro that implements std::error::Error for any struct or enum
• Automatic Display generation via #[error(”…”)] message strings with field interpolation shorthand ({field}, {0}, {field:?})
• Automatic From impls for variants annotated with #[from], enabling seamless ? operator conversions
• source() chaining via #[source] or #[from] fields, plus Backtrace capture via #[backtrace] on nightly compilers
• #[error(transparent)] support for forwarding Display/source straight through to an inner error, useful for opaque public error types

Common Use Cases

• Defining a library’s public error enum with one variant per failure mode and a human-readable message per variant
• Wrapping upstream errors (io::Error, serde_json::Error, etc.) with #[from] for seamless ? propagation across module boundaries
• Building an opaque top-level error type via #[error(transparent)] to hide internal representation from callers while keeping it free to evolve

Under The Hood

Architecture — The project splits into two crates: the public thiserror crate (src/lib.rs) re-exports a single derive macro and a handful of small runtime helper modules (private.rs, var.rs, aserror.rs, display.rs, provide.rs) that generated code relies on for trait-bound checks and provide() support, while the actual codegen lives in the thiserror-impl proc-macro crate (impl/): ast.rs parses the struct/enum into an internal model, attr.rs parses the #[error(…)], #[from], #[source], #[backtrace] attributes, fmt.rs implements the field-interpolation shorthand parser, valid.rs enforces macro-usage constraints at compile time, and expand.rs assembles the final Display/Error/From token streams. build.rs probes the active compiler version to conditionally enable nightly-only Backtrace/provide() features.

Tech Stack — Pure Rust, 2021 edition, MSRV 1.71. The impl crate depends on the standard proc-macro trio (syn, quote, proc-macro2); the public thiserror crate itself has zero runtime dependencies beyond thiserror-impl, keeping compile times and dependency trees minimal. Dual-licensed MIT OR Apache-2.0. Structured as a Cargo workspace with impl/ and tests/no-std/ as members.

Code Quality — Backed by an extensive test suite: unit-style integration tests (test_display.rs, test_from.rs, test_source.rs, test_transparent.rs, test_backtrace.rs, test_generics.rs, test_option.rs, test_path.rs, test_expr.rs, test_lints.rs) plus a 76-file trybuild tests/ui/ suite that asserts the macro’s compile-error messages stay stable and helpful. Clippy lint allowances are explicitly documented rather than silently suppressed. Over 800 commits and a decorated release history (89 releases) reflect long-term maintenance discipline from a single primary maintainer (dtolnay).

API Design — The public surface is intentionally minimal: one derive macro plus a small set of attributes (#[error], #[from], #[source], #[backtrace]). The field-interpolation shorthand (#[error(“{field}”)] instead of write!(”{}”, self.field)) removes nearly all boilerplate from the common case, and the README explicitly contrasts thiserror against anyhow to help users pick the right tool. Because generated code never appears in the crate’s public API, switching to or away from thiserror is a non-breaking change for consumers.