How does `anyhow::Error::new` wrap custom error types while preserving their `std::error::Error` implementation?

anyhow::Error::new wraps any type implementing std::error::Error plus Send + Sync + 'static into a heap-allocated ErrorImpl that stores the error alongside a vtable for dynamic dispatch, preserving access to the original error's methods through type-erased interfaces. The wrapped error can be downcast back to its original type, have its source() chain traversed, and be formatted with all its original details. This works because anyhow::Error internally stores a Box<ErrorImpl<E>> where E is the concrete error type, and the vtable provides methods like source(), downcast(), and fmt::Display that delegate to the wrapped type's implementations.

Basic anyhow::Error::new Usage

use anyhow::{Error, Result};
 
// Define a custom error type
#[derive(Debug)]
struct DatabaseError {
    message: String,
}
 
impl std::fmt::Display for DatabaseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Database error: {}", self.message)
    }
}
 
impl std::error::Error for DatabaseError {}
 
fn basic_wrapping() {
    // Wrap a custom error type
    let db_error = DatabaseError {
        message: "Connection failed".to_string(),
    };
    
    // anyhow::Error::new wraps the error
    let anyhow_error = Error::new(db_error);
    
    // Display works correctly
    println!("Error: {}", anyhow_error);
    // Output: Error: Database error: Connection failed
    
    // The wrapped error's Display implementation is preserved
}

Error::new takes any error type and wraps it, preserving its Display implementation.

The Type Requirements

use anyhow::Error;
 
// Error::new requires: std::error::Error + Send + Sync + 'static
 
#[derive(Debug)]
struct MyError {
    code: u32,
}
 
impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Error code: {}", self.code)
    }
}
 
impl std::error::Error for MyError {}
 
fn type_requirements() {
    // This works: MyError implements Error + Send + Sync + 'static
    let error = Error::new(MyError { code: 404 });
    
    // These would NOT compile:
    // - Types without std::error::Error impl
    // - Types that are !Send or !Sync
    // - Types with non-'static references
    
    // Example of what's NOT allowed:
    // struct RefError<'a>(&'a str);  // Not 'static
    // impl std::error::Error for RefError<'_> {}
    // let e = Error::new(RefError(&s));  // Won't compile: needs 'static
}

The wrapped type must implement std::error::Error, Send, Sync, and 'static.

Internal Representation: Box

use anyhow::Error;
 
// Simplified view of anyhow's internal structure:
// 
// pub struct Error {
//     inner: Box<ErrorImpl<dyn StdError>>,
// }
// 
// Where ErrorImpl<E> stores:
// - The error object: E (the actual error type)
// - A vtable for dynamic dispatch
 
#[derive(Debug)]
struct IoError {
    message: String,
}
 
impl std::fmt::Display for IoError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "IO failed: {}", self.message)
    }
}
 
impl std::error::Error for IoError {}
 
fn internal_structure() {
    let io_error = IoError {
        message: "File not found".to_string(),
    };
    
    // Error::new creates Box<ErrorImpl<IoError>>
    // This box:
    // 1. Allocates on heap (error may be large)
    // 2. Stores IoError and its vtable
    // 3. Returns fat pointer to dyn StdError
    
    let error: Error = Error::new(io_error);
    
    // The heap allocation allows:
    // - Different sized errors to be stored uniformly
    // - Error type to be erased (anyhow::Error is one type)
    // - Vtable to provide dynamic dispatch
}

The error is heap-allocated with a vtable for type-erased dynamic dispatch.

Preserving std::error::Error Methods

use anyhow::Error;
use std::error::Error as StdError;
 
#[derive(Debug)]
struct ChainError {
    message: String,
    source: Option<Box<dyn StdError + Send + Sync>>,
}
 
impl std::fmt::Display for ChainError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)
    }
}
 
impl StdError for ChainError {
    fn source(&self) -> Option<&(dyn StdError + 'static)> {
        self.source.as_ref().map(|e| e.as_ref() as &dyn StdError)
    }
}
 
fn preserved_methods() {
    let inner = std::io::Error::new(std::io::ErrorKind::NotFound, "file missing");
    let chain_error = ChainError {
        message: "Operation failed".to_string(),
        source: Some(Box::new(inner)),
    };
    
    // Wrap the chain error
    let error = Error::new(chain_error);
    
    // source() is preserved and accessible
    if let Some(source) = error.source() {
        println!("Caused by: {}", source);
    }
    
    // The entire error chain is preserved
    let mut current: &dyn StdError = &error;
    while let Some(cause) = current.source() {
        println!("Caused by: {}", cause);
        current = cause;
    }
}

The source() method from std::error::Error is preserved and works through the wrapper.

Downcasting to Original Type

use anyhow::Error;
 
#[derive(Debug)]
struct ConfigError {
    file: String,
    line: u32,
}
 
impl std::fmt::Display for ConfigError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Config error at {}:{}
", self.file, self.line)
    }
}
 
impl std::error::Error for ConfigError {}
 
fn downcasting() {
    let config_error = ConfigError {
        file: "config.toml".to_string(),
        line: 42,
    };
    
    let error: Error = Error::new(config_error);
    
    // Downcast to original type
    if let Some(config_err) = error.downcast_ref::<ConfigError>() {
        println!("File: {}, Line: {}", config_err.file, config_err.line);
    }
    
    // Downcast consuming self
    let error2 = Error::new(ConfigError {
        file: "app.toml".to_string(),
        line: 10,
    });
    
    let recovered: ConfigError = error2.downcast::<ConfigError>().unwrap();
    println!("Recovered: {} at line {}", recovered.file, recovered.line);
}

downcast_ref() and downcast() retrieve the original error type from the wrapper.

The Vtable Mechanism

use anyhow::Error;
 
// When Error::new wraps an error, it creates a vtable with:
// - display: fn(&self, &mut Formatter) -> fmt::Result
// - debug: fn(&self, &mut Formatter) -> fmt::Result
// - source: fn(&self) -> Option<&dyn Error>
// - downcast: fn(self: Box<Self>, TypeId) -> Result<Box<dyn Any>, Box<dyn Error>>
// - etc.
 
#[derive(Debug)]
struct NetworkError {
    code: i32,
}
 
impl std::fmt::Display for NetworkError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Network error code {}", self.code)
    }
}
 
impl std::error::Error for NetworkError {}
 
fn vtable_explanation() {
    let network_error = NetworkError { code: 500 };
    
    // Error::new creates vtable pointing to NetworkError's implementations
    let error: Error = Error::new(network_error);
    
    // When you call:
    // - error.to_string() -> vtable.display()
    // - error.source() -> vtable.source()
    // - error.downcast_ref() -> vtable.downcast_ref()
    
    // The vtable ensures NetworkError's implementations are called,
    // not some generic default
    
    let message = format!("{}", error);  // Uses NetworkError's Display
    assert_eq!(message, "Network error code 500");
}

The vtable delegates calls to the original error type's implementations.

Error Chains with .context()

use anyhow::{Context, Error, Result};
 
#[derive(Debug)]
struct ParseError {
    position: usize,
}
 
impl std::fmt::Display for ParseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Parse error at position {}", self.position)
    }
}
 
impl std::error::Error for ParseError {}
 
fn error_chains() -> Result<()> {
    // Create a base error
    let parse_error = ParseError { position: 42 };
    
    // Wrap and add context
    let error = Error::new(parse_error).context("Failed to parse configuration");
    
    // The context creates an error chain:
    // 1. "Failed to parse configuration"
    // 2. "Parse error at position 42"
    
    // source() traverses the chain
    let mut current: &dyn std::error::Error = &error;
    println!("Error: {}", current);
    
    while let Some(cause) = current.source() {
        println!("Caused by: {}", cause);
        current = cause;
    }
    
    // Output:
    // Error: Failed to parse configuration
    // Caused by: Parse error at position 42
    
    Err(error)
}

.context() creates error chains that preserve the original error as a source.

Comparison with Box

use anyhow::Error;
use std::error::Error as StdError;
 
#[derive(Debug)]
struct AppError {
    details: String,
}
 
impl std::fmt::Display for AppError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.details)
    }
}
 
impl StdError for AppError {}
 
fn comparison_with_box() {
    let app_error = AppError {
        details: "Something went wrong".to_string(),
    };
    
    // Box<dyn Error>: Standard library approach
    let boxed: Box<dyn StdError + Send + Sync> = Box::new(app_error);
    
    // anyhow::Error: Enhanced error handling
    let anyhow_err = Error::new(AppError {
        details: "Something went wrong".to_string(),
    });
    
    // Key differences:
    
    // 1. Downcasting
    // Box<dyn Error>: needs dynamic type checking
    let _ = boxed.downcast_ref::<AppError>();  // Works but verbose
    
    // anyhow::Error: cleaner API
    let _ = anyhow_err.downcast_ref::<AppError>();
    
    // 2. Context
    // Box<dyn Error>: no built-in context support
    // anyhow::Error: .context() for adding information
    
    // 3. Construction
    // Box<dyn Error>: requires Box::new()
    // anyhow::Error: Error::new() or .into()
}

anyhow::Error provides a cleaner API over Box<dyn Error> with additional features.

The Error Trait Implementation

use anyhow::Error;
use std::error::Error as StdError;
 
fn error_trait_impl() {
    // anyhow::Error implements std::error::Error
    // This means it can be used anywhere StdError is expected
    
    let error = Error::msg("Something failed");
    
    // Can be used as &dyn StdError
    let std_error: &dyn StdError = &error;
    println!("As StdError: {}", std_error);
    
    // Can be used in error chains
    let wrapped = Error::new(error).context("While processing");
    
    // source() works through the chain
    if let Some(source) = wrapped.source() {
        println!("Source: {}", source);
    }
}

anyhow::Error itself implements std::error::Error, so it integrates with the standard error ecosystem.

Creating Errors with Error::new vs Error::msg

use anyhow::{Error, anyhow, bail};
 
#[derive(Debug)]
struct ValidationError {
    field: String,
}
 
impl std::fmt::Display for ValidationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Validation failed for field '{}'", self.field)
    }
}
 
impl std::error::Error for ValidationError {}
 
fn creation_methods() {
    // Error::new: Wrap a custom error type
    let custom_error = Error::new(ValidationError {
        field: "email".to_string(),
    });
    
    // Error::msg: Create a simple message error
    let message_error = Error::msg("Something went wrong");
    
    // anyhow! macro: Format a message error
    let formatted_error = anyhow!("Error code: {}", 500);
    
    // bail! macro: Return early with an error
    // bail!("Critical failure");  // Returns Err(Error)
    
    // All produce anyhow::Error, but:
    // - Error::new preserves custom type (can downcast)
    // - Error::msg creates simple message (no custom type)
    
    // With custom error:
    if let Some(validation_err) = custom_error.downcast_ref::<ValidationError>() {
        println!("Field: {}", validation_err.field);
    }
    
    // With message error:
    // No custom type to downcast to
}

Error::new preserves the custom type; Error::msg creates a simple string error.

Debug Formatting Preservation

use anyhow::Error;
 
#[derive(Debug)]
struct DetailedError {
    code: u32,
    message: String,
    context: Vec<String>,
}
 
impl std::fmt::Display for DetailedError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Error {}: {}", self.code, self.message)
    }
}
 
impl std::error::Error for DetailedError {}
 
fn debug_preservation() {
    let error = DetailedError {
        code: 500,
        message: "Internal error".to_string(),
        context: vec
!["request.json".to_string(), "user_id: 123".to_string()],
    };
    
    let wrapped = Error::new(error);
    
    // Display: uses original's Display
    println!("Display: {}", wrapped);
    // Output: Error 500: Internal error
    
    // Debug: uses original's Debug
    println!("Debug: {:?}", wrapped);
    // Output: DetailedError { code: 500, message: "Internal error", context: ["request.json", "user_id: 123"] }
    
    // {:?} shows the full Debug output of the wrapped error
}

Both Display and Debug implementations are preserved through the wrapper.

Converting Errors Automatically with .into()

use anyhow::{Error, Result};
 
#[derive(Debug)]
struct AuthError {
    user: String,
}
 
impl std::fmt::Display for AuthError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Authentication failed for user '{}'", self.user)
    }
}
 
impl std::error::Error for AuthError {}
 
// Manual wrapping with Error::new
fn manual_wrapping() -> Result<()> {
    let auth_error = AuthError {
        user: "admin".to_string(),
    };
    Err(Error::new(auth_error))
}
 
// Automatic conversion with .into()
fn automatic_conversion() -> Result<()> {
    let auth_error = AuthError {
        user: "admin".to_string(),
    };
    // Into<anyhow::Error> is implemented for types with std::error::Error
    Err(auth_error.into())
}
 
// Using ? operator (also uses Into)
fn with_question_mark() -> Result<()> {
    // Function that returns AuthError
    fn authenticate() -> Result<(), AuthError> {
        Err(AuthError {
            user: "guest".to_string(),
        })
    }
    
    // ? converts AuthError -> anyhow::Error automatically
    authenticate()?;
    Ok(())
}

The From<E> implementation for anyhow::Error allows automatic conversion.

Multiple Error Types in One Function

use anyhow::{Error, Result};
use std::fs::File;
use std::io::Read;
 
#[derive(Debug)]
struct ConfigError {
    message: String,
}
 
impl std::fmt::Display for ConfigError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Config error: {}", self.message)
    }
}
 
impl std::error::Error for ConfigError {}
 
fn multiple_error_types() -> Result<()> {
    // Different error types, all converted to anyhow::Error
    
    // std::io::Error -> anyhow::Error
    let mut file = File::open("config.toml")?;
    
    // Custom ConfigError -> anyhow::Error
    let mut contents = String::new();
    file.read_to_string(&mut contents)
.map_err(|e| Error::new(e))?;
    
    // Manual conversion
    if contents.is_empty() {
        return Err(Error::new(ConfigError {
            message: "Empty config file".to_string(),
        }));
    }
    
    Ok(())
}

anyhow::Error unifies different error types through automatic conversion.

Accessing the Inner Error

use anyhow::Error;
use std::error::Error as StdError;
 
#[derive(Debug)]
struct TimeoutError {
    duration_ms: u64,
}
 
impl std::fmt::Display for TimeoutError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Operation timed out after {}ms", self.duration_ms)
    }
}
 
impl StdError for TimeoutError {}
 
fn accessing_inner() {
    let error = Error::new(TimeoutError { duration_ms: 5000 });
    
    // Method 1: downcast_ref (borrow)
    if let Some(timeout) = error.downcast_ref::<TimeoutError>() {
        println!("Timeout duration: {}ms", timeout.duration_ms);
    }
    
    // Method 2: downcast (consume)
    let error2 = Error::new(TimeoutError { duration_ms: 3000 });
    match error2.downcast::<TimeoutError>() {
        Ok(timeout) => println!("Recovered timeout: {}ms", timeout.duration_ms),
        Err(original_error) => println!("Not a TimeoutError: {}", original_error),
    }
    
    // Method 3: as inner dyn Error
    let error3 = Error::new(TimeoutError { duration_ms: 1000 });
    let inner: &dyn StdError = error3.inner();
    println!("Inner error: {}", inner);
}

Multiple methods exist to access the wrapped error depending on your needs.

Real-World Usage Pattern

use anyhow::{Context, Error, Result};
use std::error::Error as StdError;
 
// Define domain errors
#[derive(Debug)]
pub struct DatabaseError {
    pub query: String,
    pub reason: String,
}
 
impl std::fmt::Display for DatabaseError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Database error on query '{}': {}", self.query, self.reason)
    }
}
 
impl StdError for DatabaseError {}
 
#[derive(Debug)]
pub struct ValidationError {
    pub field: String,
    pub value: String,
    pub constraint: String,
}
 
impl std::fmt::Display for ValidationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Validation failed: field '{}' with value '{}' violates {}",
            self.field, self.value, self.constraint
        )
    }
}
 
impl StdError for ValidationError {}
 
// Application function using anyhow
fn process_user(id: u32, name: &str) -> Result<()> {
    // Validate input
    if name.is_empty() {
        return Err(Error::new(ValidationError {
            field: "name".to_string(),
            value: name.to_string(),
            constraint: "non-empty".to_string(),
        }));
    }
    
    // Database operation with context
    fn query_database(id: u32) -> Result<String, DatabaseError> {
        Err(DatabaseError {
            query: format!("SELECT * FROM users WHERE id = {}", id),
            reason: "Connection refused".to_string(),
        })
    }
    
    // Convert domain error to anyhow with context
    let result = query_database(id)
        .map_err(Error::new)
        .context(format!("Failed to fetch user {}", id))?;
    
    Ok(())
}
 
fn handle_errors() {
    match process_user(1, "") {
        Ok(()) => println!("Success"),
        Err(e) => {
            // Try to downcast to specific error types
            if let Some(validation) = e.downcast_ref::<ValidationError>() {
                println!("Validation error on field: {}", validation.field);
            } else if let Some(db) = e.downcast_ref::<DatabaseError>() {
                println!("Database error: {}", db.reason);
            } else {
                println!("Unknown error: {}", e);
            }
            
            // Print full chain
            let mut current: &dyn StdError = &*e;
            println!("Error chain:");
            println!("  - {}", current);
            while let Some(cause) = current.source() {
                println!("  - {}", cause);
                current = cause;
            }
        }
    }
}

Real applications use domain-specific errors wrapped in anyhow::Error with context.

Synthesis

How wrapping works:

// Error::new creates:
// 1. Heap allocation for the error
// 2. Vtable pointing to the error's implementations
// 3. Type-erased reference stored in anyhow::Error
 
let error = Error::new(MyCustomError { ... });
 
// Equivalent to:
// let boxed: Box<dyn StdError + Send + Sync> = Box::new(MyCustomError { ... });
// But with:
// - Downcasting support
// - Context chaining
// - Cleaner API

Key preservation points:

// What's preserved from the wrapped error:
// 1. Display implementation -> format!("{}", error)
// 2. Debug implementation -> format!("{:?}", error)
// 3. source() method -> error.source()
// 4. Type information -> error.downcast_ref::<T>()
 
// What's NOT preserved:
// - Direct field access (must downcast)
// - Private methods (can't call on anyhow::Error)
// - Non-error trait implementations

Vtable mechanism:

// Internal structure (simplified):
struct ErrorVtable {
    display: fn(&dyn Any, &mut Formatter) -> fmt::Result,
    debug: fn(&dyn Any, &mut Formatter) -> fmt::Result,
    source: fn(&dyn Any) -> Option<&dyn Error>,
    downcast: fn(Box<dyn Any>, TypeId) -> Result<Box<T>, Box<dyn Error>>,
}
 
// When Error::new::<T>(error):
// - Creates vtable with T's implementations
// - Stores T in Box<ErrorImpl<T>>
// - Returns type-erased Error

Key insight: anyhow::Error::new wraps custom error types by boxing them with a vtable that preserves their std::error::Error implementation—specifically their Display, Debug, and source() methods—while providing downcasting capabilities to recover the original type. The wrapper itself implements std::error::Error, making it compatible with the standard error ecosystem. This design allows anyhow::Error to unify different error types while still enabling type-specific error handling through downcasting. The heap allocation is necessary because anyhow::Error must be a single type regardless of what's wrapped inside, and the vtable enables dynamic dispatch to the original type's implementations without knowing the concrete type at compile time.

Loading page…

How does anyhow::Error::new wrap custom error types while preserving their std::error::Error implementation?

Basic anyhow::Error::new Usage

The Type Requirements

Internal Representation: Box

Preserving std::error::Error Methods

Downcasting to Original Type

The Vtable Mechanism

Error Chains with .context()

Comparison with Box

The Error Trait Implementation

Creating Errors with Error::new vs Error::msg

Debug Formatting Preservation

Converting Errors Automatically with .into()

Multiple Error Types in One Function

Accessing the Inner Error

Real-World Usage Pattern

Synthesis

How does anyhow::Error::new wrap custom error types while preserving their std::error::Error implementation?

Basic anyhow::Error::new Usage

The Type Requirements

Internal Representation: Box

Preserving std::error::Error Methods

Downcasting to Original Type

The Vtable Mechanism

Error Chains with .context()

Comparison with Box

The Error Trait Implementation

Creating Errors with Error::new vs Error::msg

Debug Formatting Preservation

Converting Errors Automatically with .into()

Multiple Error Types in One Function

Accessing the Inner Error

Real-World Usage Pattern

Synthesis

How does `anyhow::Error::new` wrap custom error types while preserving their `std::error::Error` implementation?

How does `anyhow::Error::new` wrap custom error types while preserving their `std::error::Error` implementation?