Agent skill

m06-error-handling

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

View SKILL.md on GitHub Repository
Stars 941
Forks 87

Install this agent skill to your Project

npx add-skill https://github.com/actionbook/rust-skills/tree/main/skills/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<dyn Error>" Is error granularity right?

Thinking Prompt

Before handling an error:

  1. What kind of failure is this?

    • Expected → Result<T, E>
    • Absence normal → Option<T>
    • 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:

"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<dyn Error> 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

actionbook/rust-skills

meta-cognition-parallel

EXPERIMENTAL: Three-layer parallel meta-cognition analysis. Triggers on: /meta-parallel, 三层分析, parallel analysis, 并行元认知

941 87
Explore
actionbook/rust-skills

domain-cloud-native

Use when building cloud-native apps. Keywords: kubernetes, k8s, docker, container, grpc, tonic, microservice, service mesh, observability, tracing, metrics, health check, cloud, deployment, 云原生, 微服务, 容器

941 87
Explore
actionbook/rust-skills

m07-concurrency

CRITICAL: Use for concurrency/async. Triggers: E0277 Send Sync, cannot be sent between threads, thread, spawn, channel, mpsc, Mutex, RwLock, Atomic, async, await, Future, tokio, deadlock, race condition, 并发, 线程, 异步, 死锁

941 87
Explore
actionbook/rust-skills

unsafe-checker

CRITICAL: Use for unsafe Rust code review and FFI. Triggers on: unsafe, raw pointer, FFI, extern, transmute, *mut, *const, union, #[repr(C)], libc, std::ffi, MaybeUninit, NonNull, SAFETY comment, soundness, undefined behavior, UB, safe wrapper, memory layout, bindgen, cbindgen, CString, CStr, 安全抽象, 裸指针, 外部函数接口, 内存布局, 不安全代码, FFI 绑定, 未定义行为

941 87
Explore
actionbook/rust-skills

rust-refactor-helper

Safe Rust refactoring with LSP analysis. Triggers on: /refactor, rename symbol, move function, extract, 重构, 重命名, 提取函数, 安全重构

941 87
Explore
actionbook/rust-skills

rust-skill-creator

Use when creating skills for Rust crates or std library documentation. Keywords: create rust skill, create crate skill, create std skill, 创建 rust skill, 创建 crate skill, 创建 std skill, 动态 rust skill, 动态 crate skill, skill for tokio, skill for serde, skill for axum, generate rust skill, rust 技能, crate 技能, 从文档创建skill, from docs create skill

941 87
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results