Web backend does not support arrays of samplers

Error message

Web backend does not support arrays of samplers

What it means

Raised when creating a bind group whose entry is a BindingResource::SamplerArray. The browser WebGPU API has no sampler-array binding representation this backend can use, so the mapping path panics instead of creating the bind group.

Source

Thrown at wgpu/src/backend/webgpu.rs:2319

                    mapped_buffer_binding.set_offset_f64(offset as f64);
                    if let Some(s) = size {
                        mapped_buffer_binding.set_size_f64(s.get() as f64);
                    }

                    webgpu_sys::GpuBindGroupEntry::new_with_gpu_buffer_binding(
                        binding.binding,
                        &mapped_buffer_binding,
                    )
                }
                crate::BindingResource::BufferArray(..) => {
                    panic!("Web backend does not support arrays of buffers")
                }
                crate::BindingResource::Sampler(sampler) => {
                    let sampler = &sampler.inner.as_webgpu().inner;
                    webgpu_sys::GpuBindGroupEntry::new(binding.binding, sampler)
                }
                crate::BindingResource::SamplerArray(..) => {
                    panic!("Web backend does not support arrays of samplers")
                }
                crate::BindingResource::TextureView(texture_view) => {
                    let texture_view = &texture_view.inner.as_webgpu().inner;
                    webgpu_sys::GpuBindGroupEntry::new_with_gpu_texture_view(
                        binding.binding,
                        texture_view,
                    )
                }
                crate::BindingResource::TextureViewArray(..) => {
                    panic!("Web backend does not support BINDING_INDEXING extension")
                }
                crate::BindingResource::AccelerationStructure(_) => {
                    unimplemented!("Raytracing not implemented for web")
                }
                crate::BindingResource::AccelerationStructureArray(_) => {
                    unimplemented!("Raytracing not implemented for web")
                }
                crate::BindingResource::ExternalTexture(external_texture) => {

View on GitHub (pinned to 3e11ff59bf)

Solutions

Bind each sampler as its own separate BindGroupEntry with distinct binding indices.
Restructure shaders to select filtering behavior procedurally (e.g. one combined sampler plus shader branching).
Gate sampler-array usage behind a backend check and supply an alternate bind group layout for web.

Example fix

// before
entries.push(wgpu::BindGroupEntry { binding: 3, resource: wgpu::BindingResource::SamplerArray(&samplers) });
// after
for (i, s) in samplers.iter().enumerate() {
    entries.push(wgpu::BindGroupEntry { binding: 3 + i as u32, resource: wgpu::BindingResource::Sampler(s) });
}

Defensive patterns

Strategy: validation

Validate before calling

for e in &entries {
    assert!(!matches!(e.resource, wgpu::BindingResource::SamplerArray(_)), "SamplerArray unsupported on web backend");
}

Type guard

fn has_no_sampler_array(entries: &[wgpu::BindGroupEntry]) -> bool {
    entries.iter().all(|e| !matches!(e.resource, wgpu::BindingResource::SamplerArray(_)))
}

Prevention

Bind each sampler to a distinct binding slot on web.
Replace dynamic sampler selection with shader-side branching over a few fixed samplers.
Add a debug assertion that no arrayed resources appear in web bind groups.

When it happens

Trigger: Calling device.create_bind_group with a BindGroupEntry whose resource is BindingResource::SamplerArray(&[...]) on the web backend, for a layout entry declaring an array of samplers.

Common situations: Bindless sampler arrays written for native backends; shared material/texture systems that index samplers dynamically; porting engines that use per-draw sampler selection to wasm.

Related errors

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