When the process dies, the user loses
Your CLI tool crashes with a stack trace because the user typed a typo in the filename. The process exits immediately. The user sees a wall of text starting with thread 'main' panicked at 'index out of bounds' and assumes your software is broken. If this tool runs in a CI pipeline, the build fails with a cryptic message and no clear path to recovery. If this is a web server, the worker thread dies, and the request drops.
This crash is a panic!. In Rust, a panic is the equivalent of pulling the plug on the machine because something went wrong. It's a signal that the program is in an unrecoverable state. You can write code that never panics in production. You do this by making errors part of the type system so the compiler forces you to handle them before the code runs. Panic-free code gives you control. You can retry a failed network request. You can fall back to a default configuration. You can log the error and keep serving other requests.
Errors as values, not exceptions
Rust treats errors as values. There are no unchecked exceptions that can silently escape a function. If a function can fail, it returns a Result<T, E>. This is an enum with two variants: Ok(T) for success and Err(E) for failure. The type system enforces that you deal with both cases. You cannot call a function that returns Result and ignore the possibility of failure. The compiler rejects code that discards a Result without handling it.
Think of a function like a waiter. When a function panics, the waiter drops the entire tray of food, screams, and runs out of the restaurant. The kitchen stops. The customers get nothing. When a function returns a Result, the waiter brings back an empty plate with a note explaining what went wrong. The kitchen keeps running. The customer can decide to order something else or complain to the manager. panic! is a crash. Result is a recoverable error. Rust pushes you toward Result because it makes your program robust.
Minimal example: reading a file without crashing
Here is how you read a file while handling errors gracefully. The function returns io::Result<String>, which means it returns either a String or an io::Error.
use std::fs::File;
use std::io::{self, Read};
/// Reads a file and returns the contents or an error.
fn read_file(path: &str) -> io::Result<String> {
// File::open returns Result<File, io::Error>.
// The ? operator propagates the error up if it fails.
// If open fails, read_file returns immediately with that error.
let mut file = File::open(path)?;
let mut contents = String::new();
// read_to_string can fail if the file is not valid UTF-8.
// ? handles that error too, bubbling it up to the caller.
file.read_to_string(&mut contents)?;
// If we reach here, both operations succeeded.
// Wrap the success value in Ok.
Ok(contents)
}
fn main() {
// main can return Result to let the OS handle the exit code.
// This avoids a panic in the entry point.
match read_file("input.txt") {
Ok(contents) => println!("File contents: {}", contents),
Err(e) => eprintln!("Error reading file: {}", e),
}
}
The ? operator is the workhorse of panic-free code. It checks the Result. If it's Ok, it extracts the value. If it's Err, it returns the error from the current function immediately. This eliminates nested match blocks and keeps the happy path readable.
What happens at compile time and runtime
When you compile this code, the compiler checks every call site. If read_file returns io::Result<String>, the compiler demands you handle the Err variant. You can't just call read_file("input.txt") and assign it to a String. The compiler rejects that with E0308 (mismatched types). You must use match, if let, or the ? operator. This check happens at compile time. You cannot ship code that ignores errors.
At runtime, if the file doesn't exist, File::open returns Err. The ? operator catches that Err, stops executing the rest of read_file, and returns the error to the caller. No crash. No stack trace. Just a clean value flowing back up the call stack. The caller decides what to do. In main, the match statement prints a user-friendly message. The program exits gracefully.
Convention: main as Result
Rust has a special convention for the entry point. You can make main return a Result. If main returns Err, the error is printed to stderr and the process exits with code 1. This is the standard way to write CLI tools. It removes the need for a match in main and lets you use ? all the way up.
use std::fs;
/// Entry point that returns a Result.
/// If any operation fails, the error is printed and the process exits with code 1.
fn main() -> Result<(), Box<dyn std::error::Error>> {
let contents = fs::read_to_string("config.json")?;
println!("Config loaded: {} bytes", contents.len());
Ok(())
}
This pattern is ubiquitous in the Rust ecosystem. When you see a CLI tool written in Rust, the main function almost always returns Result<(), Box<dyn std::error::Error>> or a custom error type. It keeps the code clean and ensures errors are reported to the user.
Realistic example: loading and validating configuration
Real code involves chaining operations where any step can fail. You might read a file, parse JSON, validate fields, and convert types. Here is how you handle that chain without panicking.
use std::fs;
use std::collections::HashMap;
/// Represents the application configuration.
struct Config {
db_url: String,
port: u16,
}
/// Loads and validates configuration from a JSON file.
fn load_config(path: &str) -> Result<Config, Box<dyn std::error::Error>> {
// Read the file contents.
// ? converts io::Error to Box<dyn Error> automatically via From.
let raw = fs::read_to_string(path)?;
// Parse JSON. serde_json returns its own error type.
// ? handles the conversion to Box<dyn Error>.
let data: HashMap<String, serde_json::Value> = serde_json::from_str(&raw)?;
// Validate required fields.
// get returns Option, so we use ok_or to convert None to an error.
let db_url = data.get("db_url")
.ok_or("Missing db_url in config")?
.as_str()
.ok_or("db_url must be a string")?
.to_string();
let port = data.get("port")
.ok_or("Missing port in config")?
.as_u64()
.ok_or("port must be a number")?
// u64 to u16 can fail if the number is too large.
// try_into returns Result, which ? handles.
.try_into()
.map_err(|_| "port out of range")?;
Ok(Config { db_url, port })
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = load_config("config.json")?;
println!("Connected to {} on port {}", config.db_url, config.port);
Ok(())
}
The ? operator does magic type conversion here. If the function returns Result<T, Box<dyn Error>> and a called function returns Result<T, io::Error>, ? automatically wraps the io::Error in the box. This is called the From trait magic. It lets you mix different error types without writing boilerplate. The compiler inserts the conversion code for you.
Strategies: bubble, handle, or transform
You have three main strategies for dealing with errors. Choose based on context.
Bubble the error up when the current function doesn't have enough information to handle the failure. Use ? to propagate the error to the caller. This is the default strategy for library code and low-level functions. The caller knows more about the user's intent and can decide whether to retry, log, or abort.
Handle the error locally when you can recover or provide a default. Use match or if let to inspect the error and take action. For example, if a cache lookup fails, you might fetch the data from the database and store it. Use unwrap_or or unwrap_or_else when a default value is acceptable.
Transform the error when you need to add context. Use map_err to convert a low-level error into a higher-level error with more information. This helps the caller understand what went wrong.
use std::fs::File;
/// Custom error type with context.
#[derive(Debug)]
enum AppError {
FileOpen { path: String, source: std::io::Error },
Parse { source: std::io::Error },
}
/// Opens a file and wraps the error with the path.
fn open_with_context(path: &str) -> Result<File, AppError> {
File::open(path)
.map_err(|e| AppError::FileOpen { path: path.to_string(), source: e })
}
Adding context makes debugging easier. The error message now includes the filename, not just "No such file or directory".
Pitfalls and compiler errors
Ignoring errors is the most common mistake. Developers sometimes use .unwrap() to extract a value, assuming the error is impossible. This turns a recoverable error into a panic. If the assumption is wrong, the program crashes. Never use .unwrap() in library code. It's a promise that the error is impossible. If you're wrong, you crash the caller's program.
Using ? in the wrong context triggers compiler errors. If you try to use ? in a function that returns () or a non-Result type, the compiler rejects it with E0277 (the trait bound From<std::io::Error> is not satisfied). The ? operator requires the function to return Result or Option, and the error type must be convertible to the function's error type.
Discarding a Result silently is another trap. If you call a function that returns Result and don't assign the result, the compiler warns you. This warning is controlled by the #[must_use] attribute. Most standard library functions returning Result have this attribute. If you ignore the warning, you might miss a failure. Treat #[must_use] warnings as errors. They exist to prevent silent data loss.
If you forget to handle a Result in a match arm, the compiler gives E0308 (mismatched types). You must return a value of the correct type from every arm. This ensures you don't accidentally return a success value when an error occurred.
Never unwrap in libraries. Panic is for bugs. Result is for errors. Keep them separate.
Decision: when to use panic vs result
Use Result<T, E> when a function can fail in a way the caller might want to recover from. Use panic! when the program is in an unrecoverable state, like an internal invariant violation or a bug in your logic. Use Option<T> when the absence of a value is a normal, expected outcome, not an error. Use the ? operator to propagate errors up the stack when the current function doesn't have enough context to handle the failure. Use expect("message") in tests or examples where a failure indicates a broken test setup, not a runtime error. Use a custom error type when you need to distinguish between multiple failure modes and provide specific recovery actions. Use map_err to add context to errors before propagating them. Use fn main() -> Result<(), E> for CLI tools to handle errors cleanly at the entry point.
Panic is for bugs. Result is for errors. Trust the type system to enforce the distinction.