rust-borrow-checker-error-explainer

Turn a wall of error[E0502] output into a named root cause and the least invasive fix. Read the three points every borrow error has (where the borrow starts, where the conflicting access happens, where the first borrow is used later), recognise which of a dozen recurring shapes it is (iterate-and-mutate, conditional return of a borrow, two &mut into one Vec, whole-self method borrows, move into a spawned task, temporary guard), and fix it by restructuring first. clone(), Rc<RefCell<_>> and Arc<Mutex<_>> are legitimate but come last; unsafe is never a fix for a borrow error. Three small std-only Rust programs in scripts/ do the triage: on real cargo check output (text or --message-format=json), on a single error code, and on runtime RefCell/Mutex panics.

#Trigger Conditions

Activate this skill when the user:

• Pastes cargo build / cargo check / cargo test / rust-analyzer output containing E0382, E0499, E0502, E0503, E0505, E0506, E0507, E0508, E0509, E0515, E0521, E0373, E0381, E0384, E0594, E0596, E0597, E0713, E0716, E0500/E0501/E0524, or lifetime may not live long enough
• Sees "first mutable borrow occurs here", "immutable borrow later used here", "value moved here", "returning this value requires that", "argument requires that x is borrowed for 'static", "dropped here while still borrowed", "creates a temporary value which is freed while still in use"
• Hits a runtime panic already borrowed: BorrowMutError, already mutably borrowed: BorrowError, or called Result::unwrap() on an Err value: PoisonError
• Gets "future cannot be sent between threads safely" because a MutexGuard/Rc lives across .await
• Asks how to mutate a Vec while iterating, get two &mut into a slice/HashMap, return a reference from a function, share state with thread::spawn/tokio::spawn, or store a reference in a struct
• Says "fighting the borrow checker", "should I just clone?", "do I need Rc?"

#Workflow

0. BUILD     -> once per session; std only, about 1 s each ($SKILL = this skill's folder):
                for t in parse_diagnostics explain_code runtime_panic; do
                  rustc -O --edition 2021 "$SKILL/scripts/$t.rs" -o "/tmp/$t"; done
1. CAPTURE   -> cargo check 2> build.txt   (or: cargo check --message-format=json > build.jsonl)
2. TRIAGE    -> /tmp/parse_diagnostics build.txt
                Extracts code, location and labels, names the pattern (BCK0xx), ranks fixes
3. READ      -> For each error find the three points: borrow created / conflicting use / borrow later used
                Fix the FIRST error per function; later ones are often consequences
4. CHOOSE    -> Walk the fix ladder top-down (restructure > std API > own > share > last resort)
                /tmp/explain_code E0502          # one code (or pattern, e.g. BCK002) in full
5. FIX       -> Smallest change that removes the overlap; keep the original intent and data flow
6. VERIFY    -> cargo check again; panics in tests: cargo test 2>&1 | /tmp/runtime_panic -

#Reading a Borrow Error

Every borrow conflict has the same anatomy. Find the three labels before touching code:

error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:4:5
  |
3 |     let first = &v[0];          <- 1. borrow CREATED ("immutable borrow occurs here")
4 |     v.push(4);                  <- 2. CONFLICTING access ("mutable borrow occurs here", primary ^^^)
5 |     println!("{first}");        <- 3. borrow still USED LATER ("immutable borrow later used here")

The fix always removes one of the three: end the borrow before point 2 (copy the value out, reorder), make point 2 not need the whole value (borrow a field, use a disjoint API), or make point 3 not need the reference (use an index/key, an owned copy). If label 3 is missing, the borrow is held by something that outlives the statement: a returned value ("returning this value requires that ..."), a 'static bound ("argument requires that x is borrowed for 'static"), or a destructor ("borrow might be used here, when guard is dropped").

#Error Code Decision Table

Every code with a minimal failing program and the fixed version: error-code-catalog.md.

#The Fix Ladder

Try fixes in this order; stop at the first that keeps the code clear. The script labels every fix with its tier.

Never: unsafe pointer casts, transmute of lifetimes, &T as *const T as *mut T. They turn a compile error into undefined behaviour. If a design truly needs aliasing mutation, use Cell/RefCell/atomics/Mutex.

#Core Rules

1. Shared XOR mutable. At any point, a place has either any number of live & or exactly one live &mut.
2. Liveness, not scope (NLL). A borrow lasts until its last use, not until the closing brace, unless the type has a destructor that uses it (guards, iterators holding borrows) or it flows into a return value.
3. Moves end bindings. After let b = a; / f(a) / for x in a / a.into_iter(), a is dead unless its type is Copy. Borrow (&a) when the callee does not need ownership.
4. Methods borrow all of self. self.a_mut() and self.b() conflict even if they touch different fields; direct field access (&mut self.a, &self.b) does not.
5. The checker cannot see indices. &mut v[i] and &mut v[j] conflict because i == j is possible; use APIs that prove disjointness.
6. 'static bounds mean "owns everything". thread::spawn, tokio::spawn, Box<dyn Any> need owned or Arc data; move alone does not help if what is moved is a reference.
7. Fix the first error. One bad borrow often produces several errors; recheck after each fix.
8. Clone deliberately. Cloning a small String once per request is fine; cloning a Vec inside a hot loop to silence the checker is a design smell. Prefer restructuring, then decide.

#Fix Patterns (runnable, edition 2021, MSRV noted)

Iterate-and-mutate (BCK001): collect first, then mutate.

#[derive(Clone, Debug)]
struct Order { id: u32, qty: u32 }

fn split_large(orders: &mut Vec<Order>) {
    // for o in orders.iter() { if o.qty > 10 { orders.push(..) } }   // E0502
    let extra: Vec<Order> = orders
        .iter()
        .filter(|o| o.qty > 10)
        .map(|o| Order { id: o.id + 1000, qty: o.qty - 10 })
        .collect();
    for o in orders.iter_mut().filter(|o| o.qty > 10) {
        o.qty = 10;
    }
    orders.extend(extra);
    orders.retain(|o| o.qty > 0); // remove-while-iterating: retain / extract_if (1.87+)
}

Conditional return of a borrow (BCK002): use the entry API. Current NLL rejects returning map.get_mut(k) on one path and inserting on the other (E0499), even though it is sound.

use std::collections::HashMap;

fn get_or_default<'m>(map: &'m mut HashMap<String, Vec<u32>>, key: &str) -> &'m mut Vec<u32> {
    // if let Some(v) = map.get_mut(key) { return v; }   // E0499 on the insert below
    // map.insert(key.to_owned(), Vec::new());
    map.entry(key.to_owned()).or_default()
}

fn get_or_default_lookup_first<'m>(map: &'m mut HashMap<String, Vec<u32>>, key: &str) -> &'m mut Vec<u32> {
    if map.contains_key(key) {         // check first: no borrow escapes the condition, no to_owned() on hits
        return map.get_mut(key).unwrap();
    }
    map.entry(key.to_owned()).or_default()
}

Two &mut into one slice (BCK003).

struct Account { balance: i64 }

fn transfer(accounts: &mut [Account], from: usize, to: usize, amount: i64) -> Result<(), String> {
    // let a = &mut accounts[from]; let b = &mut accounts[to];      // E0499
    let [a, b] = accounts
        .get_disjoint_mut([from, to])                              // Rust 1.86+
        .map_err(|e| format!("bad indices: {e:?}"))?;
    a.balance -= amount;
    b.balance += amount;
    Ok(())
}

fn transfer_pre_1_86(accounts: &mut [Account], from: usize, to: usize, amount: i64) {
    assert!(from != to);
    let (lo, hi) = (from.min(to), from.max(to));
    let (left, right) = accounts.split_at_mut(hi);                 // any Rust version
    let (low, high) = (&mut left[lo], &mut right[0]);
    let (a, b) = if from < to { (low, high) } else { (high, low) };
    a.balance -= amount;
    b.balance += amount;
}

Whole-self method borrows (BCK004): borrow fields, not self.

struct Cart { items: Vec<u32>, discount: u32, log: Vec<String> }

impl Cart {
    fn apply(&mut self) {
        // for i in self.items.iter_mut() { self.record(*i) }   // E0499: record takes &mut self
        let discount = self.discount;                       // Copy value out
        let log = &mut self.log;                            // disjoint field borrows are fine
        for item in self.items.iter_mut() {
            *item = item.saturating_sub(discount);
            log.push(format!("item now {item}"));
        }
    }
}

Moving out of &mut self (BCK013): Option::take, mem::take, mem::replace.

use std::mem;

enum Conn { Idle, Open(String), Closed }

struct Client { conn: Conn, pending: Vec<String>, token: Option<String> }

impl Client {
    fn close(&mut self) -> Option<String> {
        // let Conn::Open(addr) = self.conn else { .. }      // E0507 move out of borrow
        match mem::replace(&mut self.conn, Conn::Closed) {
            Conn::Open(addr) => Some(addr),
            other => { self.conn = other; None }
        }
    }
    fn drain(&mut self) -> Vec<String> { mem::take(&mut self.pending) }
    fn take_token(&mut self) -> Option<String> { self.token.take() }
}

Threads and tasks (BCK015): move owned or Arc data; scoped threads to borrow.

use std::sync::Arc;
use std::thread;

fn spawn_workers(config: Arc<String>, rows: &[u64]) -> u64 {
    let handles: Vec<_> = (0..2)
        .map(|i| {
            let config = Arc::clone(&config);               // clone the handle, move the clone
            thread::spawn(move || format!("{config}-{i}").len())
        })
        .collect();
    for h in handles { h.join().unwrap(); }

    thread::scope(|s| {                                     // Rust 1.63+: may borrow `rows`
        let (a, b) = rows.split_at(rows.len() / 2);
        // `a`/`b` are locals of this closure: `move` copies the slice references in
        let left = s.spawn(move || a.iter().sum::<u64>());
        let right = s.spawn(move || b.iter().sum::<u64>());
        left.join().unwrap() + right.join().unwrap()
    })
}

Tokio is the same rule: tokio::spawn needs Future + Send + 'static, so write tokio::spawn(async move { ... }) with owned/Arc captures, and never keep a std::sync::MutexGuard alive across .await. Details and async patterns: threads-async-and-closures.md.

RefCell panics (BCK024): end the guard before calling out.

use std::cell::RefCell;
use std::rc::Rc;

struct Bus { listeners: RefCell<Vec<Rc<dyn Fn(&Bus, &str)>>> }

impl Bus {
    fn emit(&self, msg: &str) {
        // for l in self.listeners.borrow().iter() { l(self, msg) }  // panics if a listener subscribes
        let snapshot: Vec<_> = self.listeners.borrow().clone();     // Ref dropped at the `;`
        for l in snapshot { l(self, msg); }
    }
    fn subscribe(&self, f: Rc<dyn Fn(&Bus, &str)>) { self.listeners.borrow_mut().push(f); }
}

More patterns (state machines, arenas and indices, graphs, self-referential structs, lending iterators): restructuring-patterns.md.

#Symptom -> Cause -> Fix

NLL limitations (problem case #3, cursor loops), Polonius status and two-phase borrows: nll-limitations-and-polonius.md. Ownership model, drop scopes and temporaries: ownership-and-borrowing-model.md.

#Version Notes

Full table and migration notes: version-history-and-testing.md.

#Output Format

When explaining a borrow error, answer with:

1. Diagnosis - the code, the place (self.orders, map), and the three points (created / conflicting / used later) quoted from the labels, with file:line.
2. Pattern - the named shape (BCK id when the script reports one) in one sentence: why the code is rejected.
3. Fix - the best rung of the ladder as complete before/after code that compiles on the user's edition and MSRV; name any feature that needs a newer Rust.
4. Alternatives - one or two lower rungs with their cost (allocation, refcount, runtime panic risk).
5. Verify - cargo check (and the test or --strict script run) that should now pass.

If the snippet is too short to see the conflicting use, ask for the full cargo check output or the function, and run the script on it rather than guessing.

#Scripts

Small, standard-library-only Rust programs. They read text you give them and never run cargo. Compile each once with rustc -O --edition 2021 scripts/<name>.rs -o /tmp/<name> (no Cargo project, no crates).

/tmp/parse_diagnostics build.txt                         # cargo check 2> build.txt
cargo check --message-format=json | /tmp/parse_diagnostics -
/tmp/parse_diagnostics build.jsonl --json                # machine-readable report
/tmp/parse_diagnostics build.txt --strict                # CI: exit 1 if an error is not borrow-related
/tmp/explain_code E0502                                  # also: BCK002, iterate-and-mutate, lifetime
/tmp/explain_code --list --json
cargo test 2>&1 | /tmp/runtime_panic - --strict

Exit codes (all three): 0 done, 1 with --strict when an error or panic is not a borrow/ownership problem (listed as "other", never guessed at), 2 usage error, unreadable or empty input, or an unknown code.

#Additional Resources