Composable Error Types with `thiserror` in Rust
thiserror generates boilerplate for custom Rust error types, letting you define specific, matchable errors for a library. Use it when callers need to handle different failure modes. The footgun is using it for simple app errors where anyhow would suffice.
Why it exists
Manually implementing std::error::Error, Display, and From for every custom error type is repetitive and error-prone. Rust's error handling philosophy encourages specific, typed errors, but this creates significant boilerplate for library authors who need to expose structured failure states to their users.
The mental model
Think of thiserror as a code generator for your error types. You define the what—the different error variants and their user-facing messages—in an enum, and thiserror handles the how by writing the impl Error, impl Display, and impl From blocks for you using simple attributes.
How it works
You add #[derive(Error)] to an enum or struct. The #[error("...")] attribute on each variant generates the Display implementation, allowing you to format a message and interpolate fields with {field} syntax. The #[from] attribute on a field inside a variant automatically generates an impl From<SourceError> for YourError, allowing seamless conversion from an underlying error (like io::Error) into one of your enum variants. This also correctly sets up the source() method for error chaining, which is crucial for diagnostics.
When to use it
Use thiserror when writing a library where consumers need to programmatically react to different kinds of errors. If a caller needs to distinguish between a network disconnect and a permissions error to decide whether to retry or fail fast, thiserror is the right tool. It helps you create a stable, public error API that users can match against.
When not to use it
Avoid thiserror for top-level application error handling where you just need to propagate an error up the call stack and log it. For that, anyhow::Error is simpler, as it wraps any error type without requiring you to define a new enum for every possible failure. thiserror is for defining specific error types; anyhow is for handling them opaquely.
One canonical example
A data access library might define a DataStoreError enum. One variant, Disconnect(#[from] io::Error), could be generated automatically from an I/O error during a network call. Another, Redaction(String), could be a custom error for when a key is valid but the data is not available to the caller. A third, InvalidHeader { expected: String, found: String }, could be a struct variant with detailed diagnostic information. This lets a caller handle each case differently: retry on disconnect, log the redaction, or fail on an invalid header.
Interview question
For which scenario is thiserror specifically recommended in Rust?
- a.Building a library where consumers need to programmatically differentiate between various failure modes.Correct
- b.Automatically generating error messages for all panics and unrecoverable errors in an application.
- c.Creating a single, generic error type that can wrap any underlying error for simplified error propagation.
- d.Handling top-level application errors that primarily need to be logged and propagated up the call stack.
Why? this is the answer
The card explicitly states to "Use thiserror when writing a library where consumers need to programmatically react to different kinds of errors." Option D describes the use case for `anyhow`, which the card advises against for `thiserror`.
Just read this? Test yourself on what you have been reading.
Read the original → docs.rs
- #rust
- #errors
- #libraries
- #thiserror
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on rust — each one lists the topics its interview covers.
See open roles