BorrowError

BorrowError is a runtime error type defined in the Rust standard library, specifically in the core::cell module. It is produced by the RefCell<T> type when an attempt is made to borrow the contained value in a way that violates the cell's borrowing rules. RefCell implements Rust’s interior mutability pattern, allowing values to be borrowed mutably or immutably at runtime rather than at compile time. BorrowError is returned by the try_borrow() and try_borrow_mut() methods of RefCell and the associated try_borrow methods on the Ref and RefMut types.

The error contains a boolean flag, called `mutably_borrowed`, that indicates whether the failure was due to an attempt to acquire a mutable borrow when an immutable borrow already existed, or due to a second mutable borrow attempt while one was already active. This flag lets callers differentiate between the two kinds of borrowing conflicts.

Typical causes of a BorrowError include calling RefCell::try_borrow_mut() while two immutable borrows are active, or calling try_borrow_mut() when a mutable borrow is already in place. Because RefCell performs its borrow checks at runtime, such errors typically manifest as panic conditions when the Result is not matched or when the cell is accessed through unsafe code that bypasses checks. Handling BorrowError involves refactoring code to reduce overlapping borrows, using different data structures, or moving the problematic logic to a different thread where the borrow constraints are guaranteed to be satisfied.

BorrowError is distinct from the compile‑time borrow checker errors that Rust normally generates. While the compiler enforces most borrowing rules statically, RefCell and other interior‑mutable types defer those checks to runtime to enable patterns such as dynamic proxying, thread‑local storage, and certain caching mechanisms.