--- name: rust-error-handling description: > Idiomatic Rust error handling design for libraries and applications: thiserror vs anyhow boundary decisions, error hierarchy design, context chain propagation, HTTP handler error mapping, and the common patterns that prevent error type proliferation. Use when designing error types for a new module, deciding between thiserror and anyhow, or debugging opaque error messages in production. compatibility: > Requires a Rust codebase and cargo; error-chain validation benefits from local test coverage. metadata: opensite-category: backend opensite-scope: shared opensite-visibility: public --- # Rust Error Handling ## Skill Resources - Activation and cross-agent notes: [references/activation.md](references/activation.md) Rust's error handling requires deliberate design decisions that compound across a codebase. The wrong choice at a module boundary forces changes across every caller. This skill covers the architecture decisions, not just the syntax. --- ## The Core Boundary: `thiserror` vs `anyhow` The single most important decision: **are you writing library code or application code?** | Concern | Library (`thiserror`) | Application (`anyhow`) | |---------|----------------------|------------------------| | Callers programmatically match errors | Yes | No | | Error types are part of the public API | Yes | No | | Ergonomics of error propagation | Verbose | Ergonomic (`?` just works) | | Error context chain | Manual | `context()` / `with_context()` | | When to use | `src/services/*`, any reusable module | `src/handlers/*`, `main.rs`, scripts | **The rule**: Use `thiserror` at library and service boundaries. Use `anyhow` at application boundaries (handlers, CLI entry points, scripts). Never use `anyhow` in code that other code will call and need to match on. --- ## Designing Error Hierarchies with `thiserror` ### Single-Layer Enum (Most Common) ```rust // src/services/embedding/error.rs use thiserror::Error; #[derive(Debug, Error)] pub enum EmbeddingError { #[error("embedding provider returned HTTP {status}: {message}")] ProviderError { status: u16, message: String, }, #[error("input too long: {len} tokens, max {max}")] InputTooLong { len: usize, max: usize }, #[error("embedding dimensions mismatch: expected {expected}, got {actual}")] DimensionMismatch { expected: usize, actual: usize }, #[error("network error: {0}")] Network(#[from] reqwest::Error), #[error("serialization error: {0}")] Serialization(#[from] serde_json::Error), } ``` ### Hierarchical Errors for Complex Modules When a service has subsystems, use nested error enums so callers can match at the right level: ```rust #[derive(Debug, Error)] pub enum StorageError { #[error("database error: {0}")] Database(#[from] DatabaseError), #[error("object store error: {0}")] ObjectStore(#[from] ObjectStoreError), #[error("resource not found: {id}")] NotFound { id: String }, } #[derive(Debug, Error)] pub enum DatabaseError { #[error("connection pool exhausted")] PoolExhausted, #[error("query failed: {0}")] Query(#[from] tokio_postgres::Error), #[error("migration failed: {0}")] Migration(String), } ``` ### `#[from]` vs Manual Conversion `#[from]` implements `From` for your enum. Use it when the wrapping adds no additional context. Add extra fields when context matters: ```rust // #[from] when wrapping is sufficient #[error("HTTP request failed: {0}")] Request(#[from] reqwest::Error), // Manual conversion when you need to add context #[error("failed to fetch model {model_name}: {source}")] ModelFetch { model_name: String, #[source] source: reqwest::Error, }, ``` --- ## `anyhow` for Application Code In handlers and top-level application code, `anyhow::Result` (alias for `Result`) provides ergonomic propagation with a context chain: ```rust use anyhow::{Context, Result}; async fn process_request(id: u64) -> Result { let record = db.find(id) .await .with_context(|| format!("failed to load record {id} from database"))?; let embedding = embed(&record.text) .await .context("embedding generation failed")?; store_result(id, embedding) .await .with_context(|| format!("failed to store embedding for record {id}"))?; Ok(Response::success()) } ``` The context chain makes the error message actionable: ``` failed to store embedding for record 42: connection pool exhausted: pool timeout after 30s ``` Each `.context()` call wraps the prior error, building a readable chain from innermost (root cause) to outermost (what the user was trying to do). --- ## `AppError`: Mapping Errors to HTTP Responses In Axum applications, define a central `AppError` type that implements `IntoResponse`. This is the seam between internal error types and HTTP status codes. ```rust // src/error.rs use axum::{http::StatusCode, response::{IntoResponse, Response}, Json}; use thiserror::Error; #[derive(Debug, Error)] pub enum AppError { #[error("not found: {0}")] NotFound(String), #[error("bad request: {0}")] BadRequest(String), #[error("unauthorized")] Unauthorized, #[error("internal error")] Internal(#[from] anyhow::Error), } impl IntoResponse for AppError { fn into_response(self) -> Response { let (status, message) = match &self { AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()), AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()), AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized".into()), AppError::Internal(e) => { // Log internal errors with full chain; return generic message to client tracing::error!(error = %e, "internal error"); (StatusCode::INTERNAL_SERVER_ERROR, "internal server error".into()) } }; (status, Json(serde_json::json!({ "error": message }))).into_response() } } ``` ### Handler Usage ```rust // Handlers return Result, AppError> // anyhow::Error automatically converts to AppError::Internal via #[from] pub async fn get_embedding( State(state): State, Path(id): Path, ) -> Result, AppError> { let record = state.db .find(id) .await .with_context(|| format!("record {id} not found in database")) .map_err(|e| { if is_not_found(&e) { AppError::NotFound(format!("record {id}")) } else { AppError::Internal(e) } })?; let response = build_response(record)?; Ok(Json(response)) } ``` --- ## Converting Between Error Domains When a service boundary returns a domain-specific error that needs to become an `AppError`: ```rust // Implement From for the conversion instead of using inline match everywhere impl From for AppError { fn from(e: EmbeddingError) -> Self { match e { EmbeddingError::InputTooLong { len, max } => { AppError::BadRequest(format!("input too long: {len} tokens (max {max})")) } EmbeddingError::DimensionMismatch { .. } => { AppError::Internal(anyhow::anyhow!("{e}")) } other => AppError::Internal(anyhow::anyhow!("{other}")), } } } // Now ? works cleanly in handlers pub async fn embed_handler(/* ... */) -> Result, AppError> { let embedding = embedding_service.embed(input).await?; // EmbeddingError → AppError Ok(Json(embedding.into())) } ``` --- ## Error Context Chain Best Practices ### What Makes a Good Context String ```rust // ❌ Context that doesn't help debug .context("failed")? // ❌ Context that duplicates the inner error message .context("reqwest error")? // reqwest::Error already says it's a reqwest error // ✅ Context that answers "what were we trying to do?" .with_context(|| format!("fetch model weights for model {model_id} from S3"))? // ✅ Context that includes the relevant identifier .with_context(|| format!("update embedding for resource {resource_type}/{resource_id}"))? ``` ### Log vs. Return: Choosing Where to Handle ```rust // ❌ Log AND return — the error gets reported twice async fn process() -> Result<()> { let result = do_work().await.map_err(|e| { tracing::error!("failed: {e}"); // logged here e })?; // ... Ok(()) } // ✅ Return the error with context; let the caller (handler) decide to log async fn process() -> Result<()> { do_work() .await .context("processing failed")?; Ok(()) } // ✅ In the handler — one place to log, then convert to HTTP response pub async fn handler(/* ... */) -> Result, AppError> { process().await.map_err(|e| { tracing::error!(error = %e, "request processing failed"); AppError::Internal(e) })?; Ok(Json(Response::ok())) } ``` --- ## Avoiding Common Error Design Mistakes ### Don't Box `dyn Error` in Library Code ```rust // ❌ Opaque — callers cannot match on variants pub fn parse(input: &str) -> Result> { ... } // ✅ Named enum — callers can match pub fn parse(input: &str) -> Result { ... } ``` ### Don't Overuse `unwrap` / `expect` ```rust // ❌ Panics in production, no context let value = map.get("key").unwrap(); // ✅ Propagate with context let value = map.get("key") .ok_or_else(|| anyhow::anyhow!("required key 'key' missing from config map"))?; // ✅ Use expect only for things that are truly invariants, with a message // that explains the invariant (not just "should be Some") let socket = listener.accept().expect( "TcpListener::accept should only fail if the socket is already closed, which cannot happen here" ); ``` ### Don't Mix `thiserror` Enums into `anyhow` Chains Unnecessarily ```rust // ❌ Wraps a typed error into anyhow before propagation, losing matchability let result = service.call().await .map_err(|e| anyhow::anyhow!("{e}"))?; // EmbeddingError is now opaque // ✅ Keep the typed error until the application boundary let result = service.call().await?; // propagate EmbeddingError to the handler // Handler maps EmbeddingError → AppError with full type visibility ``` --- ## Error Type Checklist When designing a new module's error type: - [ ] Is this module called by other modules? → `thiserror` enum with named variants - [ ] Is this a handler or entry point? → `anyhow::Result` for ergonomic propagation - [ ] Are callers expected to match on specific variants? → Named fields, not just `String` - [ ] Does the error need to become an HTTP response? → Implement `From for AppError` - [ ] Do you have a `String`-carrying catch-all variant? → Consider if it should be `#[source] SomeError` instead - [ ] Are you using `.context()` on every `?`? → Good. If not, add it — the chain matters in production