bevyengine/bevy · error

expected mutable reference value

Error message

expected mutable reference value

What it means

Panic raised by Return::unwrap_mut when the wrapped Return value is not the Return::Mut variant. The caller asserted a mutable-reference return that does not exist (the value is Owned or a shared Ref), violating unwrap_mut's precondition; a shared reference cannot be safely re-borrowed as mutable.

Source

Thrown at crates/bevy_reflect/src/func/return_type.rs:66

    /// # Panics
    ///
    /// Panics if the return value is not [`Self::Ref`].
    pub fn unwrap_ref(self) -> &'a dyn PartialReflect {
        match self {
            Return::Ref(value) => value,
            _ => panic!("expected reference value"),
        }
    }

    /// Unwraps the return value as a mutable reference to a value.
    ///
    /// # Panics
    ///
    /// Panics if the return value is not [`Self::Mut`].
    pub fn unwrap_mut(self) -> &'a mut dyn PartialReflect {
        match self {
            Return::Mut(value) => value,
            _ => panic!("expected mutable reference value"),
        }
    }
}

/// A trait for types that can be converted into a [`Return`] value.
///
/// This trait exists so that types can be automatically converted into a [`Return`]
/// by [`ReflectFn`] and [`ReflectFnMut`].
///
/// This trait is used instead of a blanket [`Into`] implementation due to coherence issues:
/// we can't implement `Into<Return>` for both `T` and `&T`/`&mut T`.
///
/// This trait is automatically implemented for non-reference types when using the `Reflect`
/// [derive macro]. Blanket impls cover `&T` and `&mut T`.
///
/// [`ReflectFn`]: crate::func::ReflectFn
/// [`ReflectFnMut`]: crate::func::ReflectFnMut
/// [derive macro]: derive@crate::Reflect

View on GitHub (pinned to 396ca72708)

Solutions

1. Check Return::is_mut() before unwrapping
2. Ensure the function returns a mutable reference variant before calling unwrap_mut

When it happens

Trigger: Thrown at crates/bevy_reflect/src/func/return_type.rs:66 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/3b2dffbebeb62290. Report an issue: GitHub.