---

name: m06-error-handling description: "CRITICAL: Use for error handling. Triggers: Result, Option, Error, ?, unwrap, expect, panic, anyhow, thiserror, when to panic vs return Result, custom error, error propagation, 错误处理, Result 用法, 什么时候用 panic" user-invocable: false

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

---

Thinking Prompt

Before handling an error:

1. What kind of failure is this?

   • Expected → Result<T, E>
   • Absence normal → Option
   • Bug/invariant → panic!
   • Unrecoverable → panic!

2. Who handles this?

   • Caller → propagate with ?
   • Current function → match/if-let
   • User → friendly error message
   • Programmer → panic with message

3. 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:

Copy"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)

---

Trace Down ↓

From design to implementation:

Copy"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

Library vs Application

Decision Flowchart

CopyIs 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

---

Anti-Patterns

---

Related Skills