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<&#x26;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