clawmates/skills/rust/rust-error-handling.md

name, description, when_to_use, tags

name	description	when_to_use	tags
rust-error-handling	When to use `anyhow` vs `thiserror`, how to add context, when to panic. Rust 1.97+ idioms.	Any time you write a fn returning `Result` in Rust.	rust errors

Rust error handling

Which error type

• Application binary (clawmates-server, clawmates-node) → anyhow::Result<T> everywhere. You never match on the error at runtime; you print + log + exit.
• Library crate (cm-db, cm-api, cm-runtime) → thiserror on a per-module Error enum. Callers get typed variants they can match.
• Test code → anyhow is fine even in library crates. Tests don't match on error types.

thiserror shape

use thiserror::Error;

#[derive(Debug, Error)]
pub enum DbError {
    #[error("row not found")]
    NotFound,
    #[error("workspace mismatch: expected {expected}, got {actual}")]
    WorkspaceMismatch { expected: Uuid, actual: Uuid },
    #[error(transparent)]
    Sqlx(#[from] sqlx::Error),
}

Rules:

• #[from] for exactly one wrapped external type per variant. Otherwise ? becomes ambiguous.
• #[error("...")] includes the values. Never #[error("db error")] — that's information-lossy.
• #[error(transparent)] for pass-through wrappers where the inner error's message is already sufficient.

Adding context

Every ? at a module boundary needs context. Without it, a deeply-nested sqlx::Error is unattributable.

use anyhow::Context;

let user = load(pool, id)
    .await
    .with_context(|| format!("load user {id}"))?;

• .context("...") for a static string.
• .with_context(|| ...) when the message includes runtime data (allocation is lazy — only fires on error).

When to panic

Panic is fine when:

• The invariant CAN'T be violated at runtime (unreachable!("mission_kind is validated at insert time")).
• You're in main() before the async runtime, and the config file is broken — .expect("clawmates.toml is required").
• Test-only preconditions (assert_eq! inside #[test]).

Panic is NOT fine when:

• The input came from the network.
• The input came from a config parse.
• The input came from a database row that a migration is supposed to guarantee — write an Error variant explaining WHY the row shape violates the invariant.

Backtrace hygiene

• Set RUST_BACKTRACE=1 in dev + CI. Off in prod (leaks internals).
• anyhow::Error captures a backtrace automatically. Log it via error!("op failed: {e:?}") — the ? formatter includes the chain + backtrace.