Skip to content
Skills Library
Programming · Building & coding

rust-error-handling

/rust-error-handling

Use when designing Rust error handling — thiserror vs anyhow, typed error enums, #[from] conversions, or recoverable errors vs panics. Not for ownership/borrowing (rust-core-language).

Repository
agents ↗
Licence
MIT
Last repository change
12.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when designing Rust error handling — thiserror vs anyhow, typed error enums, #[from] conversions, or recoverable errors vs panics. Not for ownership/borrowing (rust-core-language).

Original author description

Use when designing Rust error handling — thiserror vs anyhow, typed error enums, #[from] conversions, or recoverable errors vs panics. Not for ownership/borrowing (rust-core-language).

How it works

  1. Agent Workflow (MANDATORY)
  2. The rule
  3. Critical Rules
  4. Reference Guide
  5. Validation Checklist
Original SKILL.md headings · 79 lines, 551 words
SKILL.md preview
---
name: rust-error-handling
description: Use when designing Rust error handling — thiserror vs anyhow, typed error enums, #[from] conversions, or recoverable errors vs panics. Not for ownership/borrowing (rust-core-language).
versions:
  rust: "1.98.1"
  thiserror: "2"
  anyhow: "1"
references: references/thiserror-libraries.md, references/anyhow-applications.md, references/error-design.md, references/templates/library-error.md, references/templates/application-error.md
related-skills: rust-core-language
---

<objective>
This skill covers the thiserror-for-libraries, anyhow-for-applications split in Rust:
building typed error enums with #[derive(Error)] for library APIs callers can match on,
using anyhow::Result with .context()/.with_context() in application code, and
zero-boilerplate error conversion via #[from].

It also covers the recoverable-errors-vs-panics decision — Result for anything a caller
could reasonably recover from, panic!/unwrap/expect reserved for broken invariants — and
the rule that anyhow::Error must never leak into a library's public API.

Out of scope: general ownership/borrowing design belongs to rust-core-language;
async-runtime-specific error handling is not covered here.
</objective>

# Rust Error Handling

The consensus split: **thiserror for libraries, anyhow for applications.** A library
exposes a typed error its callers can `match`; an application wants one ergonomic error
type and rich context. Getting this boundary right is the whole discipline.

## Agent Workflow (MANDATORY)

1. **fuse-ai-pilot:explore-codebase** — is this crate a library (published API, other
   code depends on it) or a binary/application? That answer picks the tool.
2. **fuse-ai-pilot:research-expert** — confirm current `thiserror` / `anyhow` API
   before writing derives (verification chain: fuse-browser fast-path on
   `docs.rs/thiserror` and `docs.rs/anyhow` → Context7 → Exa).
3. After writing, run **fuse-ai-pilot:sniper** and `cargo clippy`.

## The rule

| Crate kind | Tool | Why |
|------------|------|-----|
| **Library** (others depend on it) | `thiserror` | Typed `enum`, `#[derive(Error)]`, callers can `match` on variants |
| **Application** (binary, top level) | `anyhow` | `anyhow::Result<T>`, `?` everywhere, `.context()` for breadcrumbs |
| **Simple / dep-free** | hand-written `std::error::Error` | No dependency when one or two variants suffice |

## Critical Rules

1. **Never expose `anyhow::Error` in a library's public API.** It erases the type, so
   callers cannot match or handle specific failures. Return a typed `enum` error.
   thiserror is designed to not appear in your public API — switching to/from a
   hand-written impl is not a breaking change.
2. **Applications use `anyhow`; libraries use `thiserror`.** Do not pull `anyhow` into
   a reusable library's signatures.
3. **Add context at each layer** in application code: `.context("...")` /
   `.with_context(|| ...)` turns "No such file or directory" into a traceable chain.
4. **`#[from]` for zero-boilerplate conversion**, so `?` lifts a source error into your
   enum. `#[from]` implies `#[source]` — never write both.
5. **Errors are values; panics are bugs.** Use `Result` for anything a caller could
   reasonably recover from. Reserve `panic!`/`unwrap`/`expect` for broken invariants.

## Reference Guide

### Concepts

| Topic | Reference | Load when |
|-------|-----------|-----------|
| thiserror (libraries) | [thiserror-libraries.md](references/thiserror-libraries.md) | Building a typed error enum for a library API |
| anyhow (applications) | [anyhow-applications.md](references/anyhow-applications.md) | Handling errors in a binary / top-level app |
| Error design | [error-design.md](references/error-design.md) | Shaping enums, `#[from]` conversion, recoverable vs panic, the anyhow/thiserror boundary |

### Templates

| Template | Load when |
|----------|-----------|
| [library-error.md](references/templates/library-error.md) | Need a complete thiserror library error module |
| [application-error.md](references/templates/application-error.md) | Need a complete anyhow application entry point with context |

## Validation Checklist

- [ ] Library errors are a typed `enum` deriving `thiserror::Error` — no `anyhow` in the public API
- [ ] Application code returns `anyhow::Result<T>` and adds `.context(...)`
- [ ] `#[from]` used for source conversions; no redundant `#[source]` alongside it
- [ ] `?` used instead of `unwrap()` on fallible values
- [ ] Panics only guard genuine invariants, with a reason
- [ ] `cargo clippy` clean, sniper passed
Files in this package (7)
  • .gitkeep 1 KB
  • SKILL.md 5 KB
  • references/anyhow-applications.md 3 KB
  • references/error-design.md 3 KB
  • references/thiserror-libraries.md 3 KB
  • references/templates/application-error.md 2 KB
  • references/templates/library-error.md 2 KB

Versions

RepositoryScoreLicence
This page · fusengine/agents90MIT
heyAyushh/stacc95MIT
heyAyushh/stacc95MIT
TheBushidoCollective/han95Apache-2.0
Amey-Thakur/AI-SKILLS90MIT

Database snapshot: 13.11.2026 · package version db9633994027 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100rs-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
  • 95rust-errors
    Design Rust error types and panic policy — Result over unwrap, thiserror for libraries, anyhow for binaries, context that survives the call stack. Use when code calls unwrap or expect outside tests, when designing or refactoring an error enum, when choosing between thiserror and…
  • 90rust-patterns
    Use this skill when implementing Rust-specific patterns — async/tokio patterns, ownership/borrowing strategies, error handling with thiserror/anyhow, serde serialization, FFI, concurrency with Arc/RwLock, and API patterns. This skill enforces: thiserror for library errors,…
  • 100rust-conventions
    Use when writing, reviewing, or refactoring Rust code — ownership and borrowing decisions, Result/Option error handling, the ? operator, choosing between thiserror and anyhow, module and crate organization, naming, or setting up clippy/rustfmt as a CI gate. Applies evergreen,…
  • 96rust-error
    Define, wrap, convert, classify, report or test Rust error types in hangarllm-rust with thiserror. Use when adding an error type or variant, mapping one crate's error into another, turning an error into a gateway response or Python exception, deciding retry or fault from an…
  • 100rust-errors
    Rust to TypeScript error handling patterns for Tauri apps. Use when defining Rust errors that will be passed to TypeScript, handling Tauri command errors, or creating discriminated union error types.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.