---
title: How to Create Custom Error Types in Rust
summary: Create a custom error enum in Rust and implement Display and Error traits to define specific application failure modes.
lang: en
slug: how-to-create-custom-error-types-in-rust
published: 2026-04-17T12:05:42+00:00
updated: 2026-04-25T22:00:13+00:00
canonical: https://www.rustfaq.org/en/how-to-create-custom-error-types-in-rust/
---

# How to Create Custom Error Types in Rust



## When standard errors aren't specific enough

You are building a command-line tool that downloads a file and saves it to disk. The download fails. Your code panics with a wall of text about TCP connection resets. Or worse, you catch the error and print "Something went wrong." Neither helps the user. You need to distinguish between a network glitch, a missing file, and a permission denied. You need your own error type.

Rust's standard library provides errors like `io::Error` and `ParseIntError`. These cover system operations and parsing. They do not cover your application logic. If your app requires a configuration file and the file is missing, `io::Error` tells you the OS couldn't open a path. It does not tell you that the configuration is required for the app to run. A custom error type bridges that gap. It wraps lower-level errors and adds your domain context.

## The anatomy of a custom error

A custom error type in Rust is an `enum` that implements two traits: `std::fmt::Display` and `std::error::Error`. The `enum` defines the possible failure modes. Each variant represents a distinct way things can go wrong. The traits make the enum compatible with the rest of the ecosystem.

Think of a hospital triage system. A generic error is like a patient shouting "I hurt!" The triage nurse needs more detail. Is it a broken arm? A heart attack? An allergic reaction? A custom error type is the triage form. It forces the code to specify the category of failure. The `Display` trait is the label on the form that the doctor reads. The `Error` trait is the stamp that says this form belongs in the medical records system, allowing it to be processed by standard tools.

The community convention is to derive `Debug` on every error type. Debug output is for developers reading logs. If you skip `Debug`, tools that print errors will fall back to a generic representation, which loses information. Always include `#[derive(Debug)]`.

## Minimal working example

Here is the skeleton. It defines an error with two variants, implements the required traits, and returns the error.

```rust
use std::fmt;
use std::io;

/// Errors that can occur in the application.
#[derive(Debug)]
enum AppError {
    /// An I/O operation failed.
    Io(io::Error),
    /// A requested item does not exist.
    NotFound(String),
}

// Implement Display to control the user-facing message.
impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            AppError::Io(e) => write!(f, "IO error: {}", e),
            AppError::NotFound(msg) => write!(f, "Item not found: {}", msg),
        }
    }
}

// Implement Error to mark this type as a standard error.
impl std::error::Error for AppError {}

fn main() -> Result<(), AppError> {
    // Return a custom error to demonstrate usage.
    Err(AppError::NotFound("user".to_string()))
}
```

## How the pieces fit together

The `enum` variants hold the data. `AppError::Io` wraps an `io::Error`. This preserves the underlying system error. `AppError::NotFound` holds a `String` describing what was missing. The choice of `String` avoids lifetime complications. Storing `&str` would require the error to borrow from somewhere, which makes returning the error from functions difficult. Storing `String` allocates, but errors are rare events. The allocation cost is negligible compared to the complexity of managing lifetimes in error types.

The `Display` implementation controls how the error prints when you use `{}` in a format string. This is the message the user sees. The `match` arm for `AppError::Io` delegates to the inner error's display. This keeps the output readable. The `NotFound` arm formats the message directly.

The `Error` trait is a marker. It tells the compiler and other crates that this type behaves like an error. Implementing it unlocks the `?` operator and allows the type to be stored in `Box<dyn std::error::Error>`. The empty body `impl std::error::Error for AppError {}` is sufficient for basic usage. The trait has optional methods like `source()`, which you can implement later to chain errors.

Build the dashboard with specific warning lights. Don't just show a generic red indicator.

## Making errors ergonomic with From

The `?` operator is the primary way to propagate errors in Rust. It works by calling `From::from` to convert the error type. If you return `AppError` but try to use `?` on an `io::Error`, the compiler rejects the code. You must implement `From<io::Error>` for `AppError`.

```rust
// Allow the ? operator to convert io::Error into AppError::Io.
impl From<io::Error> for AppError {
    fn from(err: io::Error) -> Self {
        AppError::Io(err)
    }
}

fn read_config() -> Result<String, AppError> {
    // The ? operator uses From to convert io::Error to AppError automatically.
    let content = std::fs::read_to_string("config.txt")?;
    Ok(content)
}
```

The `From` implementation maps the foreign error to your variant. When `read_to_string` returns an `Err(io::Error)`, the `?` operator calls `AppError::from(err)`. This returns `AppError::Io(err)`, which matches the return type of `read_config`. The error bubbles up cleanly.

The community convention is to implement `From` rather than `Into`. `Into` is automatically implemented for any type that implements `From`. Writing `From` is explicit and preferred. You will rarely write these implementations by hand in production code. The `thiserror` crate generates them using attributes. Start with manual implementations to understand the mechanics, then switch to `thiserror` for real projects.

The `?` operator is the payoff. Make `From` work so you can use it.

## Adding context and handling chains

Errors often need more than just the underlying cause. You might want to record the file path that failed, or the user ID that was invalid. You can add fields to the variant.

```rust
#[derive(Debug)]
enum AppError {
    Io(io::Error),
    /// Config file could not be read.
    ConfigRead {
        source: io::Error,
        path: String,
    },
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            AppError::Io(e) => write!(f, "IO error: {}", e),
            AppError::ConfigRead { source, path } => {
                write!(f, "Failed to read config at {}: {}", path, source)
            }
        }
    }
}

impl std::error::Error for AppError {
    // Return the underlying cause for error chaining.
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            AppError::Io(e) => Some(e),
            AppError::ConfigRead { source, .. } => Some(source),
        }
    }
}
```

The `ConfigRead` variant stores both the `io::Error` and the `path`. The `Display` implementation uses both fields to create a helpful message. The `source()` method returns the underlying error. This enables error chaining. Tools like `color-eyre` and `anyhow` use `source()` to print the full chain of causes. Implementing `source()` is optional but recommended for errors that wrap other errors. It allows debugging tools to trace the failure back to the root.

Convention aside: When you store a wrapped error in a struct-like variant, name the field `source`. This signals to readers that the field holds the cause. It also matches the naming used by the `thiserror` crate.

Treat the `source` field as the breadcrumb trail. If you can't trace the error back to the root, the chain is broken.

## Pitfalls and compiler feedback

Custom error types introduce a few common traps. The compiler usually catches them, but the messages can be dense.

If you try to use `?` on an error type without implementing `From`, the compiler rejects you with E0277 (the trait bound `AppError: From<std::io::Error>` is not satisfied). The compiler is telling you it does not know how to convert the system error into your app error. Add the `From` implementation to fix this.

If you forget to implement `Display`, you can still use the error, but printing it with `{}` falls back to `Debug`. The output might include internal details that confuse users. Always implement `Display` for user-facing errors.

If you forget to derive `Debug`, tools that rely on debug formatting will fail or produce unhelpful output. The compiler does not enforce `Debug`, but the ecosystem expects it. Add `#[derive(Debug)]` to every error type.

Storing `String` in error variants allocates memory. If you are creating errors in a tight loop, this adds up. Storing `&str` avoids allocation but introduces lifetimes. Lifetimes make the error type harder to return from functions because the error must borrow from data that lives long enough. Pick `String` for simplicity unless profiling proves allocation is the bottleneck. Errors should be rare. Optimize for clarity first.

If the compiler complains about trait bounds, check your `From` impl. The error message is usually precise about which conversion is missing.

## Choosing the right approach

Rust offers several ways to handle errors. The right choice depends on where you are in the codebase and what you need to do with the error.

Use a custom `enum` when your application has distinct failure modes that require different handling logic, like retrying a network error versus aborting on a configuration error.

Use the `thiserror` crate when you want to define the same structure with less boilerplate; it generates `Display`, `Error`, and `From` implementations automatically using attributes.

Use `anyhow::Error` or `Box<dyn std::error::Error>` when you are writing a command-line binary and need to propagate errors from dependencies without defining a custom type for every crate boundary.

Use a `struct` instead of an `enum` when an error contains multiple independent pieces of data that always appear together, rather than mutually exclusive variants.

Pick the tool that matches the boundary. Libraries define enums. Binaries use anyhow.

## Where to go next

- [What Is the Difference Between panic! and Result?](/en/what-is-the-difference-between-panic-and-result/)
- [How to Use the color-eyre Crate for Better Error Output](/en/how-to-use-the-color-eyre-crate-for-better-error-output/)
- [How to use unwrap_or and unwrap_or_else](/en/how-to-use-unwrapor-and-unwraporelse/)