existential-birds/beagle / plugins/beagle-rust/skills/rust-code-review
rust-code-review
VerifiedReviews Rust code for ownership, borrowing, lifetime, error handling, trait design, unsafe usage, and common mistakes. Use when reviewing .rs files, checking borrow checker issues, error handling patterns, or trait implementations. Covers Rust 2024 edition patterns and modern idioms.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.3 KB |
| references/async-concurrency.md | markdown | 18.2 KB |
| references/common-mistakes.md | markdown | 7.3 KB |
| references/concurrency-models.md | markdown | 12.2 KB |
| references/concurrency-primitives.md | markdown | 20.9 KB |
| references/error-handling.md | markdown | 22.6 KB |
| references/interface-design.md | markdown | 29.4 KB |
| references/lifetime-variance.md | markdown | 5.3 KB |
| references/lock-free-patterns.md | markdown | 23.3 KB |
| references/memory-ordering.md | markdown | 22.1 KB |
| references/ownership-borrowing.md | markdown | 7.5 KB |
| references/patterns-in-the-wild.md | markdown | 16.6 KB |
| references/types-layout.md | markdown | 14.5 KB |
| references/unsafe-deep.md | markdown | 19.6 KB |
references/error-handling.md
View on GitHub# Error Handling
## Critical Anti-Patterns
### 1. Unwrap in Production Code
`unwrap()` and `expect()` panic on `None`/`Err`, crashing the program. They bypass the type system's error safety guarantees.
```rust
// BAD - panics on invalid input
fn parse_config(input: &str) -> Config {
let value: Config = serde_json::from_str(input).unwrap();
value
}
// GOOD - propagates error to caller
fn parse_config(input: &str) -> Result<Config, serde_json::Error> {
serde_json::from_str(input)
}
```
`unwrap()` is acceptable in: tests, examples, and after a check that guarantees success (e.g., `if option.is_some() { option.unwrap() }` — though `.unwrap()` after match/if-let is cleaner).
### 2. Errors Without Context
Bare `?` propagation loses the "what was being attempted" context, making debugging difficult.
```rust
// BAD - caller sees "file not found" with no context
fn load_config(path: &Path) -> Result<Config, Error> {
let contents = std::fs::read_to_string(path)?;
let config: Config = toml::from_str(&contents)?;
Ok(config)
}
// GOOD - each operation adds context
fn load_config(path: &Path) -> Result<Config, Error> {
let contents = std::fs::read_to_string(path)
.map_err(|e| Error::ConfigRead { path: path.to_owned(), source: e })?;
let config: Config = toml::from_str(&contents)
.map_err(|e| Error::ConfigParse { path: path.to_owned(), source: e })?;
Ok(config)
}
```
With `anyhow`, use `.context()` / `.with_context()`:
```rust
use anyhow::Context;
fn load_config(path: &Path) -> anyhow::Result<Config> {
let contents = std::fs::read_to_string(path)
.with_context(|| format!("reading config from {}", path.display()))?;
let config: Config = toml::from_str(&contents)
.context("parsing config TOML")?;
Ok(config)
}
```
### 3. Stringly-Typed Errors
Using `String` as an error type loses structured information and makes error matching impossible.
```rust
// BAD - callers can't match on error types
fn validate(input: &str) -> Result<(), String> {
if input.is_empty() {
return Err("input is empty".to_string());
}
Ok(())
}
// GOOD - structured error types
#[derive(Debug, thiserror::Error)]
pub enum ValidationError {
#[error("input is empty")]
Empty,
#[error("input too long: {len} chars (max {max})")]
TooLong { len: usize, max: usize },
}
fn validate(input: &str) -> Result<(), ValidationError> {
if input.is_empty() {
return Err(ValidationError::Empty);
}
Ok(())
}
```
### 4. Panic for Recoverable Errors
`panic!` should be reserved for unrecoverable states (violated invariants, programmer bugs). Expected failures like I/O errors, parse failures, or network issues should return `Result`.
```rust
// BAD
fn connect(url: &str) -> Connection {
TcpStream::connect(url).unwrap_or_else(|e| panic!("connection failed: {e}"))
}
// GOOD
fn connect(url: &str) -> Result<Connection, ConnectionError> {
let stream = TcpStream::connect(url)
.map_err(|e| ConnectionError::TcpFailed { url: url.to_owned(), source: e })?;
Ok(Connection::new(stream))
}
```
### 5. Swallowing Errors
Discarding errors silently makes failures invisible.
```rust
// BAD - error silently ignored
let _ = save_to_disk(&data);
// GOOD - log if you can't propagate
if let Err(e) = save_to_disk(&data) {
tracing::error!(error = %e, "failed to save data to disk");
}
```
The exception: some errors are genuinely unactionable (e.g., `write!` to stderr, `close()` on a file you're done with). In those cases, `let _ =` with a brief comment is acceptable.
## Let-Else for Early Returns
Rust's `let-else` pattern (stable since 1.65) is cleaner than `match` for early returns on failure:
```rust
// GOOD - flat, readable early return
let Ok(json) = serde_json::from_str(&input) else {
return Err(MyError::InvalidJson);
};
// GOOD - continue/break in loops
for item in items {
let Some(value) = item.value() else {
continue;
};
process(value);
}
// Use if-let when the else branch needs computation
if let Some(result) = cache.get(&key) {
return Ok(result.clone());
} else {
let computed = expensive_compute(&key)?;
cache.insert(key, computed.clone());
return Ok(computed);
}
// NOTE (Edition 2024): Temporaries in if-let conditions are dropped
// at the end of the condition, not the end of the block. If the
// matched value borrows a temporary, bind it explicitly first.
// See ownership-borrowing.md for details.
```
## Prevent Early Allocation
Use `_else` variants when the fallback involves allocation or computation:
```rust
// BAD - format! runs even when x is Some
let val = x.ok_or(ParseError::Missing(format!("key {key}")));
// GOOD - closure only runs on None
let val = x.ok_or_else(|| ParseError::Missing(format!("key {key}")));
// BAD - Vec::new() allocates even on Ok path
let items = result.unwrap_or(Vec::new());
// GOOD - use unwrap_or_default for Default types
let items = result.unwrap_or_default();
```
## Logging and Transforming Errors
Use `inspect_err` to log and `map_err` to transform errors in a chain:
```rust
let result = do_something()
.inspect_err(|err| tracing::error!("do_something failed: {err}"))
.map_err(|err| AppError::from(("do_something", err)))?;
```
## Custom Error Structs
When a module has only one error type, a struct is simpler than an enum:
```rust
#[derive(Debug, thiserror::Error, PartialEq)]
#[error("Request failed with code `{code}`: {message}")]
struct HttpError {
code: u16,
message: String,
}
```
## Async Error Bounds
Errors in async code must be `Send + Sync + 'static` for spawned tasks:
```rust
// Ensure error types work across await boundaries
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
Ok(())
}
```
Avoid `Box<dyn std::error::Error>` (without Send + Sync) in libraries.
## Panic Alternatives
Prefer these over `panic!` for expected incomplete code:
| Macro | Use When |
|-------|----------|
| `todo!()` | Code not yet written — alerts compiler of missing implementation |
| `unreachable!()` | Logic guarantees this branch can't execute |
| `unimplemented!()` | Feature intentionally not implemented, with reason |
## thiserror Patterns
`thiserror` generates `Display` and `Error` implementations from derive macros. It's the standard choice for library error types.
```rust
#[derive(Debug, thiserror::Error)]
pub enum Error {
// Transparent: delegates Display and source() to inner error
#[error(transparent)]
Io(#[from] std::io::Error),
// Structured: carries context alongside the cause
#[error("failed to parse config at {path}")]
ConfigParse {
path: PathBuf,
#[source]
source: toml::de::Error,
},
// Simple: no underlying cause
#[error("workflow not found: {0}")]
NotFound(Uuid),
// Multiple sources via transparent wrapping
#[error(transparent)]
Database(#[from] sqlx::Error),
}
```
Hierarchical errors: subsystem error types wrap into a top-level error via `#[from]`:
```rust
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error(transparent)]
Workflow(#[from] WorkflowError),
#[error(transparent)]
Driver(#[from] DriverError),
}
```
## Result Type Alias Pattern
Crates commonly define a local `Result` alias to reduce boilerplate:
```rust
pub type Result<T> = std::result::Result<T, Error>;
// Now functions in this module just use:
pub fn load(path: &Path) -> Result<Config> { ... }
```
## Option Handling
`Option<T>` represents absence, not failure. Converting between `Option` and `Result` should be explicit about what "missing" means:
```rust
// BAD - ok_or with allocated string
let user = users.get(id).ok_or("user not found".to_string())?;
// GOOD - specific error type
let user = users.get(id).ok_or(Error::NotFound(id))?;
// GOOD - ok_or_else for expensive error construction
let user = users.get(id).ok_or_else(|| Error::NotFound(id))?;
```
## Error Trait Implementation Rules
Custom error types should implement the full Error contract for ecosystem compatibility:
1. **`Error` trait**: implement `std::error::Error`
2. **`Display`**: one-line, lowercase, no trailing punctuation — fits into larger error reports
3. **`Debug`**: usually `#[derive(Debug)]` is sufficient; include auxiliary info (ports, paths, request IDs)
4. **`Send + Sync`**: required for multithreaded contexts and `std::io::Error` wrapping
5. **`'static`**: enables downcasting and easy propagation up the call stack
```rust
#[derive(Debug)]
pub struct DecodeError {
offset: usize,
kind: DecodeErrorKind,
}
impl std::fmt::Display for DecodeError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// lowercase, no trailing punctuation
write!(f, "decode failed at offset {}: {}", self.offset, self.kind)
}
}
impl std::error::Error for DecodeError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
self.kind.source()
}
}
```
**Flag when**: a custom error type is missing `Display`, `Debug`, or `Error` implementations. With `thiserror`, these are derived automatically.
## Enumerated vs Opaque Error Strategy
Choose between enumerated and opaque errors based on whether callers need to distinguish error cases:
| Strategy | When to Use | Example |
|----------|-------------|---------|
| **Enumerated** (`enum`) | Callers take different actions per error variant | I/O vs parse vs auth errors in a web handler |
| **Opaque** (`Box<dyn Error>` or struct) | Callers only log/propagate, don't match on variants | Image decoder, internal library errors |
**Flag when**:
- A library exposes `Box<dyn Error>` when callers demonstrably need to match on specific error cases
- An error enum has 20+ variants that callers never match on — consider an opaque wrapper to simplify the API
## Error Chain Traversal with `source()`
`Error::source()` provides the underlying cause, enabling error chain traversal for backtraces and diagnostics.
```rust
fn print_error_chain(err: &dyn std::error::Error) {
let mut current = Some(err);
while let Some(e) = current {
eprintln!(" caused by: {e}");
current = e.source();
}
}
```
**Check for**: error types that wrap an inner error but don't implement `source()` — the chain breaks and root cause is hidden.
With `thiserror`, `#[source]` and `#[from]` attributes handle this automatically:
```rust
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error("database query failed")]
Database {
#[source] // wires up Error::source()
source: sqlx::Error,
},
}
```
## Type-Erased Error Composition
`Box<dyn Error + Send + Sync + 'static>` enables heterogeneous error handling in applications:
```rust
fn process() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
let data = std::fs::read_to_string("input.txt")?; // io::Error
let parsed: Config = toml::from_str(&data)?; // toml::de::Error
Ok(())
}
```
**Check for**: `Box<dyn Error>` (without `Send + Sync`) in library code — this prevents use in multithreaded contexts. Always prefer `Box<dyn Error + Send + Sync + 'static>` or a concrete type.
Note: `Box<dyn Error + Send + Sync + 'static>` itself does not implement `Error`. If you need a type-erased error that also implements `Error`, define a wrapper type or use `anyhow::Error`.
## Downcasting with `Error::downcast_ref()`
Downcasting recovers the concrete error type from a `dyn Error`. Requires the `'static` bound.
```rust
fn handle_error(err: &(dyn std::error::Error + 'static)) {
if let Some(io_err) = err.downcast_ref::<std::io::Error>() {
if io_err.kind() == std::io::ErrorKind::WouldBlock {
// handle non-blocking retry
return;
}
}
// generic error handling
eprintln!("error: {err}");
}
```
**Flag when**: error types are not `'static` — this prevents downcasting and limits composability. Avoid placing non-static references in error types unless strictly necessary.
## `From` Implementations for `?` Ergonomics
The `?` operator uses `From` to convert between error types. Implementing `From<SourceError> for MyError` enables seamless `?` propagation.
```rust
// Manual From implementation
impl From<std::io::Error> for AppError {
fn from(err: std::io::Error) -> Self {
AppError::Io(err)
}
}
// With thiserror — #[from] generates the From impl
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error(transparent)]
Io(#[from] std::io::Error),
}
```
**Check for**:
- Missing `From` implementations causing verbose `.map_err()` chains when `?` would suffice
- Implement `From`, not `Into` — the `?` operator uses `From` internally
- Conflicting `#[from]` attributes: two variants with `#[from]` for the same source type won't compile
## Try Blocks for Scoped Error Handling
Try blocks (still unstable as of Edition 2024, behind `#![feature(try_blocks)]`) scope `?` to a block instead of the entire function:
```rust
#![feature(try_blocks)]
fn do_work() -> Result<(), Error> {
let resource = Resource::acquire()?;
let result: Result<(), Error> = try {
step_one(&resource)?;
step_two(&resource)?;
};
resource.cleanup(); // always runs, even if steps failed
result
}
```
**Check for**: functions that need cleanup before returning errors — `try` blocks avoid the pattern of manually catching and re-raising. Until stabilized, the drop-guard or RAII pattern is the stable alternative.
## Opaque vs Enumerated Errors
Jon Gjengset frames this as a binary choice driven by **caller need**, not author convenience: will the caller branch on the variant, or only log and propagate?
- **Enumerated** (`pub enum Error { ... }`) — caller takes different action per cause. Each variant should carry the underlying cause (e.g. `In(io::Error)` and `Out(io::Error)` are two `io::Error`s but the discriminant tells the caller *which* stream failed).
- **Opaque** — caller will only log/propagate. Two flavors: a struct with private fields and limited accessors (when bounded info is still useful — offset, status code), or `Box<dyn Error + Send + Sync + 'static>` (full erasure).
```rust
// Enumerated: callers branch on this
pub enum CopyError {
In(std::io::Error),
Out(std::io::Error),
}
// Opaque wrapper: callers cannot match, but can downcast if documented
pub struct MyError(Box<dyn std::error::Error + Send + Sync + 'static>);
```
Tradeoffs: enum locks in your variant set as a public API (adding a non-`#[non_exhaustive]` variant is a breaking change), but enables exhaustive pattern matching. Opaque keeps the variant set internal but forfeits pattern matching — callers can only inspect via `source()` or documented downcasts. See [interface-design.md](interface-design.md) for `#[non_exhaustive]` rules on public error enums.
**Flag**:
- [FILE:LINE] ENUM_VARIANTS_DROP_CAUSE — error enum variants like `In` / `Out` with no inner `io::Error` — wraps lose the only useful information.
- [FILE:LINE] OPAQUE_HIDES_BRANCH_INFO — opaque error hides info callers demonstrably branch on (retryable vs fatal) — promote to enum or expose an inspector.
## The Custom Error Trait Set
Any custom error type that ships in a public API should satisfy `Error + Display + Debug + Send + Sync + 'static`. Each bound is load-bearing:
- **`Error`** — `source()` is how the chain-traversal machinery walks to the root cause.
- **`Display`** — one-line, lowercase, no trailing punctuation, so it composes into larger error reports.
- **`Debug`** — carries auxiliary diagnostic info (ports, paths, request IDs) that doesn't belong in `Display`.
- **`Send + Sync`** — required in async/multithreaded code; without it the error can't cross an `await` or a `spawn`, and it won't compose with `std::io::Error` cleanly.
- **`'static`** — required by `dyn Error` for downcasting (`Any::type_id` vtable comparison) and to avoid lifetime contamination across the call stack.
```rust
// Audit fields: Rc<...>, RefCell<...>, raw pointers, or borrowed refs
// break Send/Sync/'static respectively.
#[derive(Debug, thiserror::Error)]
#[error("decode failed at offset {offset}")]
pub struct DecodeError { offset: usize, source_id: u64 }
```
**Flag**:
- [FILE:LINE] ERROR_FIELD_NOT_SEND — error type contains `Rc<T>` or `*const T` — breaks `Send + Sync`. Switch to `Arc` or owned data.
- [FILE:LINE] ERROR_BORROWS_INPUT — error type holds `&'a str` from request data — blocks `'static`, prevents downcasting and propagation. Own the data (`String`).
## Special Error Cases
Jon calls out four special cases worth flagging in review:
- **`Result<T, ()>` is usually wrong.** `()` doesn't implement `Error`, so the value can't be type-erased to `Box<dyn Error>` and is painful with `?`. If the failure carries no detail, switch to `Option<T>` (which says "nothing to return, no handling required"). If you must keep `Result` semantics for `#[must_use]`, define a unit struct that implements `Error`.
- **`std::thread::Result<T>` is `Result<T, Box<dyn Any + Send + 'static>>`** — note `Any`, not `Error`. The `Err` value is whatever was passed to `panic!`, often a `&'static str` or `String`. Calling `.source()` or `Display` on it is wrong; either downcast to a known payload type, propagate it via `resume_unwind`, or just `.unwrap()`.
- **The never type `!` / `Infallible`** for errors that cannot occur. `Result<T, Infallible>` lets you match a trait signature without panicking on `unwrap` — the compiler knows no `Err` value can ever be constructed.
- **Boxing on the hot path has allocation cost.** Errors are rare, so boxing a large variant keeps `Result<T, E>` small — but a fallible function called in a tight loop will pay the allocation cost on every error. Use `Cow<'static, str>` or fixed-shape errors for hot loops.
**Flag**:
- [FILE:LINE] RESULT_UNIT_USED_AS_OPTION — `fn f() -> Result<T, ()>` returned and callers treat it as absence — switch to `Option<T>` or a unit-struct error.
- [FILE:LINE] THREAD_RESULT_AS_ERROR — `JoinHandle::join()` payload treated as `dyn Error` (calling `.source()` or `Display`) — it's `Box<dyn Any>`. Downcast or `resume_unwind`.
- [FILE:LINE] BOXED_ERROR_HOT_LOOP — `Result<_, Box<MyError>>` returned from a function called per-iteration in a hot loop — allocation per failure; consider a fixed-shape error or unboxed enum.
## `?` Uses `From`, Not `Into`
`?` desugars to (roughly) `match expr { Ok(v) => v, Err(e) => return Err(From::from(e)) }`. The conversion is literally `From::from`, not `Into::into`. Implementing only `Into<OuterErr> for InnerErr` will *not* enable `?` propagation, even though `From` implies `Into`.
```rust
// Will NOT enable `?` from InnerErr to OuterErr
impl Into<OuterErr> for InnerErr { /* ... */ }
// Correct: implement From, get Into for free, and `?` works
impl From<InnerErr> for OuterErr { fn from(e: InnerErr) -> Self { /* ... */ } }
```
Old crates that only implement `Into` are common offenders — `?` will fail to compile against them with a confusing message about `From` not being implemented.
**Flag**:
- [FILE:LINE] INTO_NOT_FROM — error conversion implemented as `impl Into<Outer> for Inner` — `?` calls `From::from`, not `Into::into`. Reverse the impl direction.
## Deferred Cleanup with `?` — The Surprising Bug
A function that needs cleanup on the error path before propagating will *skip* the cleanup whenever `?` short-circuits:
```rust
fn do_the_thing() -> Result<(), Error> {
let thing = Thing::setup()?;
step_one(&thing)?; // if this errors, cleanup is skipped
step_two(&thing)?;
thing.cleanup(); // only runs on the success path
Ok(())
}
```
Three fixes, in order of preference:
- **RAII guard (stable, idiomatic).** Move cleanup into `Drop`. The compiler runs destructors on every exit path, including `?` early returns.
- **`try` blocks** (still unstable behind `#![feature(try_blocks)]`). Scope `?` to a block; cleanup runs after.
- **Explicit `match`.** Verbose but stable: bind the intermediate `Result`, run cleanup, then propagate.
```rust
struct Thing;
impl Drop for Thing { fn drop(&mut self) { /* cleanup */ } }
// Now `?` cannot skip cleanup — Drop fires on every exit.
```
**Flag**:
- [FILE:LINE] CLEANUP_SKIPPED_BY_QMARK — resource setup followed by `?` calls and a manual `cleanup()` / `close()` / `release()` after — the `?` early-return skips cleanup. Use `Drop` (RAII) or scope cleanup in a `try` block.
- [FILE:LINE] MANUAL_DROP_GUARD_LEAK — explicit `mem::forget` or `ManuallyDrop` on a guard followed by `?` — leaks the resource on error. Restructure so the guard owns the cleanup.
## `#[error(transparent)]` (thiserror)
`#[error(transparent)]` marks a variant that is a thin wrapper around an inner error type. `Display` and `source()` delegate to the inner error unchanged — the wrapper is invisible to logs and chain traversal.
```rust
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error(transparent)]
Io(#[from] std::io::Error), // displays exactly like the io::Error
#[error("config invalid at {path}")]
Config { path: PathBuf, #[source] source: toml::de::Error },
}
```
Use it when the variant adds no semantic information — the inner type is already the "real" error. Do *not* use it when you have context to add (a path, a request ID); use `#[error("...")]` with a `#[source]` field instead so the wrapping shows up in logs.
**Flag**:
- [FILE:LINE] TRANSPARENT_HIDES_CONTEXT — `#[error(transparent)]` on a variant that *should* be carrying context (path, ID) — the inner error's message alone won't tell users what was being attempted. Switch to `#[error("...")]` + `#[source]`.
- [FILE:LINE] TRANSPARENT_DUPLICATE_DISPLAY — `#[error(transparent)]` paired with a manual `Display` impl that also prints the inner error — double-prints in error chains. Drop one.
## Review Questions
1. Are all `unwrap()` / `expect()` calls in production code justified?
2. Do errors carry context about what operation failed?
3. Are error types structured (enums/structs) rather than stringly-typed?
4. Is `panic!` reserved for unrecoverable invariant violations?
5. Are errors propagated or logged, not silently swallowed?
6. Is `thiserror` used for library errors, `anyhow` for application errors?
7. Are `_else` variants used when fallbacks involve allocation?
8. Do async error types satisfy `Send + Sync + 'static` bounds?
9. Is `inspect_err` used for error logging instead of match arms?
10. Do custom error types implement the full contract (`Error`, `Display`, `Debug`, `Send + Sync + 'static`)?
11. Is `Error::source()` implemented for wrapped errors to enable chain traversal?
12. Are `From` implementations provided for `?` ergonomics instead of verbose `.map_err()` chains?
13. Is the error strategy (enumerated vs opaque) appropriate for how callers interact with errors?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |