What causes "Bin should be present" in bevyengine/bevy?

Update Bevy to the newest patch release for that minor line.

Bin should be present

Error message

Bin should be present

What it means

representative_entity() (mod.rs:532) takes the first bin index from bin_key_to_bin_index and expects the corresponding slot in bins to be occupied; 'Bin should be present' fires when that slot is None (on the free list). It indicates the key-to-index map and the bin free-list have desynchronized - an internal invariant break in RenderMultidrawableBins, not a user input error.

Source

Thrown at crates/bevy_render/src/render_phase/mod.rs:531

{
    /// Creates a new [`RenderMultidrawableBatchSet`] containing an empty set of
    /// bins.
    fn new() -> RenderMultidrawableBatchSet<BPI> {
        RenderMultidrawableBatchSet {
            gpu_buffers: RenderMultidrawableBatchSetGpuBuffers::new(),
            bin_key_to_bin_index: HashMap::default(),
            bins: vec![],
            bin_free_list: vec![],
            indirect_parameters_offset_to_bin_index: vec![],
            binned_mesh_instance_index_to_entity: vec![],
            instance_count: 0,
        }
    }

    /// Returns the first entity in the first bin (if there is one).
    pub(crate) fn representative_entity(&self) -> Option<MainEntity> {
        let first_bin_index = self.bin_key_to_bin_index.values().next()?;
        let first_bin = self.bin(*first_bin_index).expect("Bin should be present");
        first_bin
            .entity_to_binned_mesh_instance_index
            .keys()
            .next()
            .copied()
    }

    /// Returns the [`RenderMultidrawableBin`] for the given [`RenderBinIndex`].
    pub(crate) fn bin(&self, bin_index: RenderBinIndex) -> Option<&RenderMultidrawableBin> {
        self.bins
            .get(bin_index.0 as usize)
            .and_then(|bin| bin.as_ref())
    }

    /// Inserts an entity with the given uniform index into the bin with the
    /// given key.
    fn insert(
        &mut self,

View on GitHub (pinned to 221e52ae32)

Solutions

Update Bevy to the newest patch release for that minor line.
As a workaround, avoid the multidrawable path (use the regular binned/instance paths) until fixed.
Report upstream with a minimal reproduction; this expect guards an engine invariant, not user input.

Defensive patterns

Strategy: fallback

Prevention

Pin a Bevy version where the issue does not reproduce until a fix ships.
Reduce spawn/despawn churn during GPU-driven rendering or disable the multidrawable path if unstable on your version.
Report reproducible internal-invariant panics to the Bevy tracker with the backtrace.

When it happens

Trigger: The bins free-list marked a slot empty while bin_key_to_bin_index still mapped a key to that index (or a bin was freed without dropping its key mapping); afterwards representative_entity() is called during GPU-driven render graph building.

Common situations: Almost always an engine-side bookkeeping bug in the multidraw bin lifecycle; surfaces during heavy spawn/despawn churn with multidraw batching enabled, or after Bevy upgrades.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of bevyengine/bevy@221e52ae32 (2026-08-20). Data as JSON: /api/errors/e53738003be16545. Report an issue: GitHub.