Rust: called `Option::unwrap()` on a `None` value

The exact panic

let items = vec![1, 2, 3];
let first = items.iter().find(|&&x| x > 10).unwrap();
// thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/main.rs:3:52
// note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

An Option<T> is either Some(value) or None — Rust's way of forcing you to acknowledge that a value might be absent. Calling .unwrap() says “I'm certain this is Some; give me the value, and crash if I'm wrong.” When the Option is actually None, that's exactly what happens: the current thread panics (and the program aborts unless something catches it, e.g. with catch_unwind, or the panic strategy is set to abort, in which case the whole process ends immediately). The fix is never to make unwrap “work” — it's to decide what should happen when the value is missing, and use the method that expresses it.

The unwrap ladder: choose by what should happen on None

Fix 1: supply a fallback with unwrap_or / unwrap_or_else

let port = config.get("port").map(String::as_str).unwrap_or("8080");   // eager default
let id = cache.lookup(key).unwrap_or_else(|| generate_id());           // lazy — only runs on None
let count = maybe_count.unwrap_or_default();                            // 0 for numbers, "" for String

Use unwrap_or for a cheap constant, unwrap_or_else when computing the fallback is expensive (the closure only runs on None), and unwrap_or_default when the type's Default is what you want. One footgun to know about: config.get("port").unwrap_or(&"8080".to_string()) looks reasonable but won't compile — the "8080".to_string() temporary is dropped at the end of the statement, so the reference to it can't outlive the borrow (E0716: temporary value dropped while borrowed). Rust only extends a temporary's lifetime when the &expr sits directly in a let binding, not inside a method-call argument. Going through &str via .map(String::as_str), as above, sidesteps the problem entirely.

Fix 2: branch explicitly with match or if let

match users.get(&id) {
    Some(user) => println!("found {}", user.name),
    None => println!("no user with id {id}"),
}

// or, when you only care about the Some case:
if let Some(user) = users.get(&id) {
    println!("found {}", user.name);
}

Fix 3: propagate None with the ? operator

In a function that returns Option, ? extracts the value from a Some (it doesn't unwrap in the panicking sense) and returns None from the whole function the instant any step is absent — letting you chain lookups without a pyramid of matches:

fn first_admin_email(users: &[User]) -> Option<&str> {
    let admin = users.iter().find(|u| u.is_admin)?;   // None here → return None
    let email = admin.email.as_deref()?;              // None here → return None
    Some(email)
}

The enclosing function must return Option (or Result) for ? to be allowed — that's what it short-circuits into.

Fix 4: if it really can't be None, use expect

When None would genuinely be a bug — an invariant your program guarantees — a panic is acceptable, but make it self-explaining. Prefer expect over unwrap:

// ❌ bare panic, no context for whoever hits it
let cfg = load_config().unwrap();

// ✅ same panic, but it documents the assumption
let cfg = load_config().expect("config was validated at startup — this can't be None");

The two produce identical behavior on None, but expect's message tells the next engineer which invariant was violated instead of leaving them to reverse-engineer it from a line number.

Fix 5: transform without unwrapping (map, and_then)

Often you don't need the raw value at all — you need to do something with it if it's present. The combinator methods let you keep working inside the Option and never risk a panic:

// map: transform the inner value if Some, stay None otherwise
let len: Option<usize> = name.map(|n| n.len());

// and_then: chain another Option-returning step (flatMap)
let city: Option<&str> = user.address.as_ref().and_then(|a| a.city.as_deref());

// filter: keep Some only if a predicate holds
let positive = count.filter(|&n| n > 0);

These read top-to-bottom and compose cleanly, which is why idiomatic Rust reaches for them long before unwrap. When you finally need a concrete value at the end of a chain, close it out with one of the ladder's safe endings (unwrap_or, match, or ?).

Turning Option into Result with ok_or

When a missing value should become a real error to propagate — not just a None — convert with ok_or / ok_or_else, then use ? to bubble it up as an Err:

fn load_user(id: u32) -> Result<User, AppError> {
    let user = cache.get(&id).ok_or(AppError::NotFound(id))?;   // None → Err, propagated
    Ok(user.clone())
}

The same applies to Result

.unwrap() on a Result that's Err panics identically (“called Result::unwrap() on an Err value”). The ladder maps across: unwrap_or/unwrap_or_else for a fallback, match to branch on Ok/Err, ? to propagate the error, and expect for a documented invariant.

Debugging checklist

• ✓ Decide first: on None, do you want a default, a branch, an early return, or a crash?
• ✓ Default → unwrap_or / unwrap_or_else / unwrap_or_default
• ✓ Branch → match or if let Some(x)
• ✓ Propagate → ? (function must return Option/Result)
• ✓ Genuinely impossible → expect("reason"), never bare unwrap()
• ✓ Set RUST_BACKTRACE=1 to see the full stack to the panic