gfx-rs/wgpu · error

Only BufferUsages::COPY_SRC may be used when Features::MAPPA

Error message

Only BufferUsages::COPY_SRC may be used when Features::MAPPABLE_PRIMARY_BUFFERS is not enabled. Specified buffer usages: {buffer_usages:?}

What it means

Panic in Upload Belt/InitEncoder construction (new_with_buffer_usages): the requested buffer_usages contain bits beyond MAP_WRITE | COPY_SRC while Features::MAPPABLE_PRIMARY_BUFFERS is disabled on the device. The faulty input is buffer_usages.

Source

Thrown at wgpu/src/util/belt.rs:105

    /// - If enabled: any usage is valid.
    /// - If disabled: only [`COPY_SRC`](BufferUsages::COPY_SRC) can be used.
    #[track_caller]
    pub fn new_with_buffer_usages(
        device: Device,
        chunk_size: BufferAddress,
        mut buffer_usages: BufferUsages,
    ) -> Self {
        let (sender, receiver) = mpsc::channel();

        // make sure anything other than MAP_WRITE | COPY_SRC is only allowed with MAPPABLE_PRIMARY_BUFFERS.
        let extra_usages =
            buffer_usages.difference(BufferUsages::MAP_WRITE | BufferUsages::COPY_SRC);
        if !extra_usages.is_empty()
            && !device
                .features()
                .contains(Features::MAPPABLE_PRIMARY_BUFFERS)
        {
            panic!("Only BufferUsages::COPY_SRC may be used when Features::MAPPABLE_PRIMARY_BUFFERS is not enabled. Specified buffer usages: {buffer_usages:?}");
        }
        // always set MAP_WRITE
        buffer_usages.insert(BufferUsages::MAP_WRITE);

        StagingBelt {
            device,
            chunk_size,
            buffer_usages,
            active_chunks: Vec::new(),
            closed_chunks: Vec::new(),
            free_chunks: Vec::new(),
            sender: Exclusive::new(sender),
            receiver: Exclusive::new(receiver),
        }
    }

    /// Allocate a staging belt slice of `size` to be copied into the `target` buffer
    /// at the specified offset.

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Request Features::MAPPABLE_PRIMARY_BUFFERS on the device if extra usages are required
2. Restrict belt buffer usages to MAP_WRITE | COPY_SRC when the feature is off

When it happens

Trigger: Thrown at wgpu/src/util/belt.rs:105 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gfx-rs/wgpu@3e11ff59bf (2026-09-03). Data as JSON: /api/errors/63b8dda660ad7eb7. Report an issue: GitHub.