handling-rust-errors

# Rust Error-Stack Patterns HASH-specific error handling patterns using the `error-stack` crate for consistent, debuggable error handling across the Rust codebase. ## Core Principles **HASH uses `error-stack` exclusively for error handling:** ✅ **DO:** - Use `Report<MyError>` for all error types - Use concrete error types: `Report<MyError>` - Import `Error` from `core::error::` (not `std::error::`) - Import `ResultExt as _` for trait methods ❌ **DON'T:** - Use `anyhow` or `eyre` crates - Use `Box<dyn Error>` (except in tests/prototyping) - Use `Report<Box<dyn Error>>` - Use `thiserror` (use `derive_more` instead) ## HashQL Compiler Exception **HashQL compiler code uses a different error handling approach.** Code in `libs/@local/hashql/*` uses the `hashql-diagnostics` crate instead of `error-stack`. This is because compiler errors require rich formatting capabilities: - Source spans pointing to exact code locations - Multiple labeled regions within the same diagnostic - Fix suggestions with replacement text - Severity levels (error, warning, hint) **Which approach to use:** | Location | Error Handling | | -------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `libs/@local/hashql/*` (compiler code) | Use `hashql-diagnostics` → See [writing-hashql-diagnostics](../writing-hashql-diagnostics/SKILL.md) skill | | Everywhere else | Use `error-stack` patterns from this skill | Traditional `error-stack` patterns still apply for HashQL infrastructure code (CLI, file I/O, configuration) that doesn't involve compiler diagnostics. ## Quick Start Guide Choose the reference that matches your current task: ### Defining Errors **Use when:** Creating new error types or error enums - Define error types with `derive_more` - Error enum patterns and variants - Implement the `Error` trait - Error type hierarchies ### Propagating Errors **Use when:** Handling `Result` types, using `?` operator - Convert errors with `.change_context()` and `.change_context_with()` - Add context with `.attach()` and `.attach_with()` - Error conversion patterns ### Documenting Errors **Use when:** Writing doc comments for fallible functions - `# Errors` section format - Link error variants - Document runtime errors - Test error conditions ## Common Quick Patterns ### Creating an Error ```rust use error_stack::Report; return Err(Report::new(MyError::NotFound)) .attach(format!("ID: {}", id)); ``` ### Propagating with Context ```rust use error_stack::ResultExt as _; some_result .change_context(MyError::OperationFailed) .attach("Additional context")?; ``` ### Lazy Context (for expensive operations) ```rust use error_stack::ResultExt as _; expensive_operation() .change_context(MyError::OperationFailed) .attach_with(|| format!("Debug info: {:?}", expensive_computation()))?; ``` ## References - [Defining Errors](references/defining-errors.md) - Creating new error types or error enums - [Propagating Errors](references/propagating-errors.md) - Handling `Result` types, using `?` operator - [Documenting Errors](references/documenting-errors.md) - Writing doc comments for fallible functions