handling-rust-errors
/handling-rust-errors
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
Original author description
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
How it works
- Core Principles
- HashQL Compiler Exception
- Quick Start Guide
- Common Quick Patterns
- References
SKILL.md preview
---
name: handling-rust-errors
description: HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
license: AGPL-3.0
metadata:
triggers:
type: domain
enforcement: suggest
priority: high
keywords:
- error
- Result
- Report
- error-stack
- change_context
- attach
- ResultExt
intent-patterns:
- "\\b(handle|create|define|propagate|convert)\\b.*?\\berror\\b"
- "\\bReport<.*>\\b"
---
# 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
Files in this package (4)
- SKILL.md 4 KB
- references/defining-errors.md 6 KB
- references/documenting-errors.md 8 KB
- references/propagating-errors.md 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · zjunlp/skills | 100 | MIT |
| hashintel/hash | 100 | MIT |
Identical content appears in 5 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version daa99c86a66f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95rust-error-handling
Guides Rust error handling strategy. Use when choosing between Result/Option/panic, using anyhow vs thiserror, propagating errors with ?, or designing custom error types. - 95rust-error-handling
Use when Rust error handling with Result, Option, custom errors, thiserror, and anyhow. Use when handling errors in Rust applications. - 95rust-error-handling
Guides Rust error handling strategy. Use when choosing between Result/Option/panic, using anyhow vs thiserror, propagating errors with ?, or designing custom error types. - 100error-handling
Implement Go error handling patterns including error wrapping, sentinel errors, custom error types, and error handling conventions. Use when handling errors, creating error types, or implementing error propagation. Trigger words include "error", "panic", "recover", "error… - 95go-error-handling
Use when Go error handling with error wrapping, sentinel errors, and custom error types. Use when handling errors in Go applications. - 100go-error-handling
Go error handling patterns, wrapping, sentinel errors, custom error types, and the errors package. Grounded in Effective Go, Go Code Review Comments, and production-proven idioms. Use when implementing error handling, designing error types, debugging error chains, or reviewing…