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:

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

use error_stack::Report;

return Err(Report::new(MyError::NotFound))
    .attach(format!("ID: {}", id));

Propagating with Context

use error_stack::ResultExt as _;

some_result
    .change_context(MyError::OperationFailed)
    .attach("Additional context")?;

Lazy Context (for expensive operations)

use error_stack::ResultExt as _;

expensive_operation()
    .change_context(MyError::OperationFailed)
    .attach_with(|| format!("Debug info: {:?}", expensive_computation()))?;

References

• •Defining Errors - Creating new error types or error enums
• •Propagating Errors - Handling Result types, using ? operator
• •Documenting Errors - Writing doc comments for fallible functions