thiserror
Derive macro for implementing std::error::Error for custom Rust error types. Write error enums with #[derive(Error)] and #[error('description')] attributes — thiserror generates the Error implementation, Display, and From conversions automatically. The standard approach for defining typed errors in Rust library crates, complementary to anyhow for application code.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
MIT/Apache 2.0. Zero runtime, memory-safe Rust. Proc-macro crate — proc-macro security of the derive macro itself is the concern for supply chain.
⚡ Reliability
Best When
You're writing a Rust library crate and need typed error enums that library users can match on — the standard approach for Rust library error handling.
Avoid When
You're writing application binary code — use anyhow for simpler error propagation without typed enums. thiserror is for library authors.
Use Cases
- • Define typed error enums for Rust agent library crates that callers can pattern match programmatically
- • Create structured error types for agent API clients where callers need to handle specific error variants
- • Implement error conversions from underlying errors (io::Error, serde_json::Error) to domain-specific error types
- • Build agent SDK crates with clear, documented error types that users can handle specifically
- • Define precise error types for agent state machine transitions where each failure mode has distinct handling
Not For
- • Application binary crates — use anyhow for application error handling where typed errors aren't needed
- • Simple one-off errors — anyhow::anyhow!('message') or anyhow::bail!() is simpler for application code
- • Complex error hierarchies across many crates — consider the error ecosystem design carefully
Interface
Authentication
Local library — no authentication required. MIT/Apache 2.0 dual licensed.
Pricing
MIT/Apache 2.0 dual licensed. Zero cost.
Agent Metadata
Known Gotchas
- ⚠ #[from] generates From<SourceError> for YourError — enables ? operator conversion but each source type can only appear ONCE in the enum
- ⚠ #[source] vs #[from]: #[from] = From conversion + source; #[source] = only source (no From); use #[from] when you want ? operator conversion
- ⚠ Error display format: #[error('Failed to parse {0}: {1}')] uses positional or named fields; #[error('IO error: {source}')] references field by name
- ⚠ Transparent errors: #[error(transparent)] forwards Display and source to the inner error — useful for simple newtype wrappers
- ⚠ thiserror v2 vs v1: v2 has improved diagnostics and some syntax changes — check migration guide; both are widely used
- ⚠ Combining thiserror and anyhow is idiomatic: library defines error types with thiserror, application uses anyhow::Error and converts with ?
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for thiserror.
Scores are editorial opinions as of 2026-03-06.