m06-error-handling

SKILL.md

Error Handling

Layer 1: Language Mechanics

Core Question

Is this failure expected or a bug?

Before choosing error handling strategy:

Can this fail in normal operation?

Who should handle this failure?

What context does the caller need?

Error → Design Question

Pattern
Don't Just Say
Ask Instead

unwrap panics
"Use ?"
Is None/Err actually possible here?

Type mismatch on ?
"Use anyhow"
Are error types designed correctly?

Lost error context
"Add .context()"
What does the caller need to know?

Too many error variants
"Use Box"
Is error granularity right?

Thinking Prompt

Before handling an error:

What kind of failure is this?

Expected → Result<T, E>

Absence normal → Option

Bug/invariant → panic!

Unrecoverable → panic!

Who handles this?

Caller → propagate with ?

Current function → match/if-let

User → friendly error message

Programmer → panic with message

What context is needed?

Type of error → thiserror variants

Call chain → anyhow::Context

Debug info → anyhow or tracing

Trace Up ↑

When error strategy is unclear:

"Should I return Result or Option?"
    ↑ Ask: Is absence/failure normal or exceptional?
    ↑ Check: m09-domain (what does domain say?)
    ↑ Check: domain-* (error handling requirements)

Situation
Trace To
Question

Too many unwraps
m09-domain
Is the data model right?

Error context design
m13-domain-error
What recovery is needed?

Library vs app errors
m11-ecosystem
Who are the consumers?

Trace Down ↓

From design to implementation:

"Expected failure, library code"
    ↓ Use: thiserror for typed errors

"Expected failure, application code"
    ↓ Use: anyhow for ergonomic errors

"Absence is normal (find, get, lookup)"
    ↓ Use: Option<T>

"Bug or invariant violation"
    ↓ Use: panic!, assert!, unreachable!

"Need to propagate with context"
    ↓ Use: .context("what was happening")

Quick Reference

Pattern
When
Example

Result<T, E>
Recoverable error
fn read() -> Result<String, io::Error>

Option<T>
Absence is normal
fn find() -> Option<&Item>

?
Propagate error
let data = file.read()?;

unwrap()
Dev/test only
config.get("key").unwrap()

expect()
Invariant holds
env.get("HOME").expect("HOME set")

panic!
Unrecoverable
panic!("critical failure")

Library vs Application

Context
Error Crate
Why

Library
thiserror
Typed errors for consumers

Application
anyhow
Ergonomic error handling

Mixed
Both
thiserror at boundaries, anyhow internally

Decision Flowchart

Is failure expected?
├─ Yes → Is absence the only "failure"?
│        ├─ Yes → Option<T>
│        └─ No → Result<T, E>
│                 ├─ Library → thiserror
│                 └─ Application → anyhow
└─ No → Is it a bug?
        ├─ Yes → panic!, assert!
        └─ No → Consider if really unrecoverable

Use ? → Need context?
├─ Yes → .context("message")
└─ No → Plain ?

Common Errors

Error
Cause
Fix

unwrap() panic
Unhandled None/Err
Use ? or match

Type mismatch
Different error types
Use anyhow or From

Lost context
? without context
Add .context()

cannot use ?
Missing Result return
Return Result<(), E>

Anti-Patterns

Anti-Pattern
Why Bad
Better

.unwrap() everywhere
Panics in production
.expect("reason") or ?

Ignore errors silently
Bugs hidden
Handle or propagate

panic! for expected errors
Bad UX, no recovery
Result

Box everywhere
Lost type info
thiserror

Related Skills

When
See

Domain error strategy
m13-domain-error

Crate boundaries
m11-ecosystem

Type-safe errors
m05-type-driven

Mental models
m14-mental-model