thiserror best practices

Use when designing or reviewing structured Rust error types with thiserror.

Mental model

• thiserror is for typed error definitions, especially in libraries, domain layers, and stable internal boundaries.
• Prefer thiserror when callers benefit from knowing what kinds of failures occurred, not just that “something went wrong”.
• Treat error types as part of the interface of a module or crate.

Error type design

• Use enums when the failure modes are meaningfully different and callers may branch on them.
• Keep variants semantically clear; each variant should represent a real category of failure, not a random implementation detail.
• Prefer a small, stable error surface over dozens of ultra-specific variants that leak internal mechanics.

Sources and wrapping