Home

masterror Wiki

Framework-agnostic application error types for Rust

---

Table of Contents

Getting Started

• Quick Start
• Installation
• First Example

Core Documentation

• Application Guide - Build production-ready error handling
• Rust Error Handling Basics - Foundation concepts
• Patterns and Troubleshooting - Best practices and solutions

Features

• Colored Terminal Output - Professional CLI error visibility
  • Terminal Detection Guide - How automatic detection works
  • Color Scheme Reference - Complete color mapping
  • Integration Guide - Using with tracing, log, and web frameworks
  • Troubleshooting - Common issues and solutions
  • Migration Guide - Upgrading from non-colored versions

Reference

• Masterror Error Handling - Complete reference

---

Quick Start

masterror provides a stable, framework-agnostic error taxonomy for Rust applications. Perfect for:

• REST APIs (Axum, Actix Web)
• gRPC services (Tonic)
• CLI applications
• Libraries with clear error contracts

Key Features

• Type-safe error handling - Categorize errors by kind (BadRequest, Unauthorized, Internal, etc.)
• Machine-readable codes - Attach structured error codes for clients
• Framework integration - First-class support for Axum, Actix Web, Tonic, and more
• Rich context - Preserve error chains without exposing internals to clients
• Zero-cost abstractions - Efficient stack-based storage with Arc for shared data

---

Installation

Add to your Cargo.toml:

[dependencies]
masterror = "0.24"

For framework integration:

[dependencies]
masterror = { version = "0.24", features = ["axum"] }  # Axum support
masterror = { version = "0.24", features = ["actix"] } # Actix Web support
masterror = { version = "0.24", features = ["tonic"] } # gRPC/Tonic support

---

First Example

use masterror::{AppError, AppErrorKind, AppResult};

fn validate_age(age: u32) -> AppResult<()> {
    if age < 18 {
        return Err(AppError::bad_request("Must be 18 or older"));
    }
    Ok(())
}

fn main() {
    match validate_age(16) {
        Ok(_) => println!("Valid!"),
        Err(e) => {
            // For users: clean, structured error
            println!("Error: {}", e.message);
            println!("Status: {}", e.status());

            // For developers: full context
            if let Some(context) = e.context() {
                eprintln!("Debug: {:?}", context);
            }
        }
    }
}

Output:

Error: Must be 18 or older
Status: 400

---

Where to Go Next

• New to Rust error handling? Start with Rust Error Handling Basics
• Building an API? Read the Application Guide
• Need patterns or troubleshooting? Check Patterns and Troubleshooting
• Want complete reference? See Masterror Error Handling

---

Contributing

Found an issue or have suggestions?

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This Wiki accepts contributions!

---

License

MIT OR Apache-2.0