When error types clash
You are writing a function that loads a configuration file. Your function signature promises to return Result<Config, AppError>. Inside, you call std::fs::read_to_string, which returns Result<String, std::io::Error>. You try to use the ? operator to propagate the result, and the compiler stops you. The error types do not match. std::io::Error is not AppError.
You cannot return the IO error directly. You need to translate it. You need to take the raw system error, wrap it in your application's error type, and pass it up the chain. That is exactly what map_err does. It transforms the error variant of a Result while leaving the success variant untouched.
The relay race for errors
Think of a Result as a package moving through a pipeline. The package is either Ok (contains the data) or Err (contains a problem). Most operations in the pipeline only care about the data. They assume the package is good. If the package is bad, it needs to be handled differently.
map_err is a station on the pipeline that only activates when the package is bad. If the package is Ok, it slides right past map_err without slowing down. If the package is Err, map_err catches it, hands the error to a closure you provide, and expects the closure to return a new error. The package continues down the line, now carrying the transformed error.
This separation is powerful. You can transform errors without writing boilerplate to handle the success case. The success path remains a straight line. The error path gets the attention it needs.
Minimal example: parsing with context
The most common use case is adding context to a generic error. A library function returns a raw error that tells you what went wrong but not where. map_err lets you inject the missing context.
fn parse_age(input: &str) -> Result<u32, String> {
// parse returns Result<u32, ParseIntError>
// We need Result<u32, String> to match the return type
input.parse::<u32>()
// map_err only runs if parse returns Err
.map_err(|e| format!("Failed to parse age '{input}': {e}"))
}
fn main() {
match parse_age("25") {
Ok(age) => println!("Age is {age}"),
Err(e) => println!("Error: {e}"),
}
match parse_age("abc") {
Ok(age) => println!("Age is {age}"),
Err(e) => println!("Error: {e}"),
}
}
The closure receives the ParseIntError and returns a String. The Result type changes from Result<u32, ParseIntError> to Result<u32, String>. The success value 25 passes through unchanged. The error gets wrapped in a message that includes the input string.
Run this code and you see the difference. A valid input prints the age. An invalid input prints the enriched error message. The closure captures input from the surrounding scope, which is why the error message includes the string that failed to parse.
Convention aside: When you call map_err, the closure should focus on transformation. If you need to perform side effects or complex logic, consider using match instead. map_err signals to the reader that you are simply reshaping the error.
Under the hood: lazy evaluation
map_err is lazy. The closure you pass to it does not execute unless the Result is actually an error. This matters for performance and correctness.
fn expensive_transformation(e: std::io::Error) -> String {
// Imagine this does heavy work or I/O
println!("Transforming error");
format!("IO Error: {e}")
}
fn read_data() -> Result<Vec<u8>, String> {
std::fs::read("data.bin")
// The closure is NOT called if read succeeds
.map_err(expensive_transformation)
}
fn main() {
// If the file exists, "Transforming error" never prints
let result = read_data();
if result.is_ok() {
println!("Data loaded successfully");
}
}
If std::fs::read returns Ok, map_err returns Ok immediately. The closure expensive_transformation is never invoked. This means you can use map_err with closures that are expensive to run, or even closures that might panic, without worrying about them executing on the success path. The compiler guarantees the closure only sees errors.
This laziness also means map_err takes a closure, not a value. You cannot pass a pre-computed error. You must provide a function that computes the new error from the old one. The signature is FnOnce(E) -> F. The closure consumes the original error and produces the new one.
Ah-ha reveal: Because the closure captures variables from the environment, map_err is the idiomatic way to add context without allocating a new error type. You can capture file paths, user IDs, or request metadata and inject them into the error message on the fly.
Realistic example: wrapping library errors
In real applications, you often wrap errors from dependencies into your own error enum. This keeps your public API clean and lets you handle errors uniformly. map_err bridges the gap between library errors and your error type.
use std::fs;
use std::io;
#[derive(Debug)]
enum AppError {
Io(io::Error),
Config(String),
}
impl std::fmt::Display for AppError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
AppError::Io(e) => write!(f, "IO error: {e}"),
AppError::Config(msg) => write!(f, "Config error: {msg}"),
}
}
}
fn load_config() -> Result<String, AppError> {
fs::read_to_string("config.toml")
// Transform io::Error into AppError::Io
.map_err(AppError::Io)
}
fn main() {
match load_config() {
Ok(content) => println!("Config loaded: {} bytes", content.len()),
Err(e) => println!("Failed: {e}"),
}
}
Here, map_err takes the variant AppError::Io directly. You do not need a closure because AppError::Io is a constructor that accepts an io::Error. The compiler infers that you want to map the error using this constructor. This is cleaner than writing .map_err(|e| AppError::Io(e)).
Convention aside: When your error variant is a simple wrapper, pass the variant directly to map_err. It reads better and reduces noise. Reserve closures for cases where you need to format a message or perform a conversion that the variant constructor cannot do alone.
This pattern enables the ? operator later. Once the error type matches the function's return type, you can chain ? to propagate.
fn process_config() -> Result<(), AppError> {
let content = load_config()?;
// ... process content ...
Ok(())
}
Without map_err, load_config would return io::Error, and process_config could not use ? because the types would mismatch. map_err aligns the types so the rest of the code can flow naturally.
Pitfalls: map vs map_err and the match trap
The most common mistake is confusing map and map_err. They look similar but touch opposite sides of the Result.
map transforms the Ok value. map_err transforms the Err value. If you use map when you meant map_err, you transform the success value and leave the error untouched. This often leads to type errors downstream.
fn bad_example() -> Result<String, String> {
"123".parse::<u32>()
// This transforms the u32, not the error
.map(|n| format!("Number: {n}"))
}
fn main() {
// This fails to compile
// bad_example() returns Result<String, ParseIntError>
// but the function signature promises Result<String, String>
let _ = bad_example();
}
The compiler rejects this with E0308 (mismatched types). It tells you the function returns Result<String, ParseIntError> but the signature requires Result<String, String>. The error type did not change because map only touches Ok.
Another pitfall is overusing map_err when ? works. If the error types implement From, the ? operator handles the conversion automatically.
fn good_example() -> Result<String, Box<dyn std::error::Error>> {
// ParseIntError implements Into<Box<dyn Error>>
// ? converts automatically. No map_err needed.
let n: u32 = "123".parse()?;
Ok(format!("{n}"))
}
Using map_err here adds noise. The ? operator is concise and idiomatic. Use map_err only when ? cannot convert the error, or when you need to add context that ? cannot provide.
Pitfall closer: Check the variant before you transform. map touches success. map_err touches failure. Mixing them up breaks your logic instantly.
Decision: choosing the right transformation
Rust provides several ways to handle errors. Pick the tool that matches the shape of your data flow.
Use map_err when you need to transform the error type to match your function's return signature. Use map_err when you want to add context to an error, like wrapping a raw IO error with a message about which file failed. Use ? alone when the error types align or when From is implemented for automatic conversion. Use map when you need to transform the success value inside an Ok variant. Use unwrap_or_else when you want to handle the error locally and return a fallback value instead of propagating. Use match when you need to branch on the error type or perform complex logic that a closure cannot express cleanly.
Decision closer: Pick the tool that matches the shape of your data flow. If you are just reshaping the error, map_err is the precise instrument. If you are recovering or branching, reach for something else.