{"record":{"id":"59c8e6fa84b9e29e","repo":"bevyengine/bevy","slug":"invalidsamplertype","errorCode":"InvalidSamplerType","errorMessage":"At binding index {0}, the provided image sampler `{1}` does not match the required sampler type(s) `{2}`.","messagePattern":"At binding index (.+?), the provided image sampler `(.+?)` does not match the required sampler type\\(s\\) `(.+?)`\\.","errorType":"error_code","errorClass":"AsBindGroupError","httpStatus":null,"severity":"error","filePath":"crates/bevy_render/src/render_resource/bind_group.rs","lineNumber":646,"sourceCode":"        force_no_bindless: bool,\n    ) -> Vec<BindGroupLayoutEntry>\n    where\n        Self: Sized;\n\n    fn bindless_descriptor() -> Option<BindlessDescriptor> {\n        None\n    }\n}\n\n/// An error that occurs during [`AsBindGroup::as_bind_group`] calls.\n#[derive(Debug, Error)]\npub enum AsBindGroupError {\n    /// The bind group could not be generated. Try again next frame.\n    #[error(\"The bind group could not be generated\")]\n    RetryNextUpdate,\n    #[error(\"Create the bind group via `as_bind_group()` instead\")]\n    CreateBindGroupDirectly,\n    #[error(\"At binding index {0}, the provided image sampler `{1}` does not match the required sampler type(s) `{2}`.\")]\n    InvalidSamplerType(u32, String, String),\n}\n\n/// A prepared bind group returned as a result of [`AsBindGroup::as_bind_group`].\npub struct PreparedBindGroup {\n    pub bindings: BindingResources,\n    pub bind_group: BindGroup,\n}\n\nimpl PreparedBindGroup {\n    pub(crate) fn unprepare(&self) -> BindGroupBuilder {\n        let mut data_buffer = vec![];\n        BindGroupBuilder {\n            binding_resources: UnpreparedBindingResources(\n                self.bindings\n                    .iter()\n                    .map(|(binding, owned_binding_resource)| {\n                        let unprepared_binding_resource = match owned_binding_resource {","sourceCodeStart":628,"sourceCodeEnd":664,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_render/src/render_resource/bind_group.rs#L628-L664","documentation":"AsBindGroupError::InvalidSamplerType(index, provided, required) is reported by as_bind_group when the sampler attached to an image does not match the sampler type(s) the bind group layout requires at that binding index: filtering vs non-filtering vs comparison. The payload names the offending binding index, the sampler actually provided, and the type(s) the shader/layout declared, so you can locate the mismatch precisely.","triggerScenarios":"Declaring a comparison sampler (sampler_comparison) in WGSL while the image keeps the default filtering TextureSampler; using a non-filterable texture format with a filtering sampler declaration; or specifying the wrong sampler type in #[derive(AsBindGroup)] binding attributes.","commonSituations":"Shadow-mapping materials that forget to switch the sampled image to a comparison sampler descriptor; integer or depth formats (non-filterable) sampled as if filterable; shader code copied between filtering and non-filtering contexts; upgrading engines where sampler defaults changed.","solutions":["Make the image's sampler match the shader: for sampler_comparison set image.sampler = TextureSampler::Descriptor(SamplerDescriptor { compare: Some(CompareFunction::LessEqual), ..default() }).","For non-filterable formats, use TextureSampler::NonFiltering and keep the shader declaration consistent.","Use the binding index from the message to find the exact field/attribute to fix; check the derive attributes' sampler types."],"exampleFix":"// before: shader declares a comparison sampler but the image keeps the default filtering one\n// @group(2) @binding(0) var shadow_sampler: sampler_comparison;\nlet image = assets.get(&shadow_texture_handle).unwrap(); // sampler == TextureSampler::Default\n\n// after\nlet mut image = Image::new(...);\nimage.sampler = TextureSampler::Descriptor(bevy_render::render_resource::SamplerDescriptor {\n    compare: Some(bevy_render::render_resource::CompareFunction::LessEqual),\n    ..Default::default()\n});","handlingStrategy":"validation","validationCode":"// Keep image sampler and shader declaration in sync before building materials:\nfn sampler_for_shader(needs_comparison: bool) -> TextureSampler {\n    if needs_comparison {\n        TextureSampler::Descriptor(SamplerDescriptor {\n            compare: Some(CompareFunction::LessEqual),\n            ..Default::default()\n        })\n    } else {\n        TextureSampler::Default\n    }\n}","typeGuard":null,"tryCatchPattern":"match material.as_bind_group(&layout, device, queue, &mut param) {\n    Err(AsBindGroupError::InvalidSamplerType(index, provided, required)) => {\n        error!(\"binding {index}: sampler {provided} does not satisfy {required}\");\n        // fix image.sampler or the shader declaration, then retry\n    }\n    other => other?,\n}","preventionTips":["Whenever a shader declares sampler_comparison, set the image's sampler to a comparison descriptor in the same change.","Use TextureSampler::NonFiltering for non-filterable (integer/depth) formats and keep declarations consistent.","Use the error's binding index to jump straight to the offending field instead of guessing."],"tags":["bevy","bind-group","sampler","texture","shader-mismatch"],"backgroundTag":"binding-type-mismatch","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}