Skip to content
Skills Library
Programming · Building & coding

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.

Repository
skills ↗
Licence
MIT
Last repository change
05.07.2026

Assessment and security

100/ 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.
Content35 / 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
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.07.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

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

  1. Core Principles
  2. HashQL Compiler Exception
  3. Quick Start Guide
  4. Common Quick Patterns
  5. References
Original SKILL.md headings · 110 lines, 383 words
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

RepositoryScoreLicence
This page · zjunlp/skills100MIT
hashintel/hash100MIT

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…

Feedback and reports

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