bevyengine/bevy · error

Failed to map buffer

Error message

Failed to map buffer

What it means

After submitted commands complete, bevy's readback system calls `map_async(Read, ...)` on each staging buffer and unwraps the callback result with `.expect("Failed to map buffer")`. A mapping failure means wgpu refused the map: the buffer was already mapped or destroyed, or the device was lost.

Source

Thrown at crates/bevy_render/src/gpu_readback.rs:409

            }
        }
    }
}

/// Move requested readbacks to mapped readbacks after commands have been submitted in render system
#[expect(
    clippy::drain_collect,
    reason = "draining preserves the capacity of `requested`, which is refilled every frame"
)]
fn map_buffers(mut readbacks: ResMut<GpuReadbacks>) {
    let requested = readbacks.requested.drain(..).collect::<Vec<GpuReadback>>();
    for readback in requested {
        let slice = readback.buffer.slice(..);
        let entity = readback.entity;
        let buffer = readback.buffer.clone();
        let tx = readback.tx.clone();
        slice.map_async(wgpu::MapMode::Read, move |res| {
            res.expect("Failed to map buffer");
            let buffer_slice = buffer.slice(..);
            let data = buffer_slice.get_mapped_range().unwrap();
            let result = Vec::from(&*data);
            drop(data);
            buffer.unmap();
            if let Err(e) = tx.try_send((entity, buffer, result)) {
                debug!("Failed to send readback result: {}", e);
            }
        });
        readbacks.mapped.push(readback);
    }
}

// Utils

/// Round up a given value to be a multiple of [`wgpu::COPY_BYTES_PER_ROW_ALIGNMENT`].
pub(crate) const fn align_byte_size(value: u32) -> u32 {
    RenderDevice::align_copy_bytes_per_row(value as usize) as u32

View on GitHub (pinned to 4805ca792c)

Solutions

1. Keep the app and device alive until pending readbacks resolve (take the result from the spawned GpuReadback entity before exiting)
2. Don't despawn readback entities or drop the source buffer before results arrive
3. If it happens mid-run, look for the original device-loss error elsewhere in wgpu logs; this panic is usually a symptom, not the cause

When it happens

Trigger: A requested GPU readback whose staging buffer cannot be mapped — device loss between request and map, buffer destroyed/invalidated first, or abnormal shutdown while readbacks are still in flight.

Common situations: App exit during an in-flight readback; driver reset mid-session; dropping or mutating the source ShaderBuffer in the same frame the readback is requested.

Related errors

• Please use a more specific shader stage: https://github.com/
• Tried to read past the end of the buffer (start: {start}, si
• Cannot call `ReflectComponent::reflect_mut` on component {na
• Cannot call `ReflectComponent::reflect_unchecked_mut` on com
• component should represent a type.

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