tomevault-io 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 |
Source: nature-lang/nature — distributed by TomeVault.