OpenParable
Skip to content
← Back to skills

Handling Rust Errors

Development
handling-rust-errors

Handling Rust Errors is an Agent Skill for development published in the hashintel/hash repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hashintel/hash/blob/HEAD/.claude/skills/handling-rust-errors/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/handling-rust-errors, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

LocationError Handling
libs/@local/hashql/* (compiler code)Use hashql-diagnostics → See writing-hashql-diagnostics skill
Everywhere elseUse 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

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