{"record":{"id":"4f19df533e5b83a4","repo":"bevyengine/bevy","slug":"failed-to-build-bind-group-0","errorCode":null,"errorMessage":"Failed to build bind group: {0}","messagePattern":"Failed to build bind group: (.+?)","errorType":"exception","errorClass":"PrepareAssetError","httpStatus":null,"severity":"error","filePath":"crates/bevy_render/src/erased_render_asset.rs","lineNumber":24,"sourceCode":"use bevy_asset::RenderAssetUsages;\nuse bevy_asset::{Asset, AssetEvent, AssetId, Assets, UntypedAssetId};\nuse bevy_ecs::{\n    prelude::{Commands, IntoScheduleConfigs, Local, MessageReader, ResMut, Resource},\n    schedule::{ScheduleConfigs, SystemSet},\n    system::{ScheduleSystem, StaticSystemParam, SystemParam, SystemParamItem, SystemState},\n    world::{FromWorld, Mut},\n};\nuse bevy_log::{debug, error};\nuse bevy_platform::collections::{HashMap, HashSet};\nuse bevy_render::render_asset::RenderAssetBytesPerFrameLimiter;\nuse core::marker::PhantomData;\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum PrepareAssetError<E: Send + Sync + 'static> {\n    #[error(\"Failed to prepare asset\")]\n    RetryNextUpdate(E),\n    #[error(\"Failed to build bind group: {0}\")]\n    AsBindGroupError(AsBindGroupError),\n}\n\n/// The system set during which we extract modified assets to the render world.\n#[derive(SystemSet, Clone, PartialEq, Eq, Debug, Hash)]\npub struct AssetExtractionSystems;\n\n/// Describes how an asset gets extracted and prepared for rendering.\n///\n/// In the [`ExtractSchedule`] step the [`ErasedRenderAsset::SourceAsset`] is transferred\n/// from the \"main world\" into the \"render world\".\n///\n/// After that in the [`RenderSystems::PrepareAssets`] step the extracted asset\n/// is transformed into its GPU-representation of type [`ErasedRenderAsset`].\npub trait ErasedRenderAsset: Send + Sync + 'static {\n    /// The representation of the asset in the \"main world\".\n    type SourceAsset: Asset + Clone;\n    /// The target representation of the asset in the \"render world\".","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_render/src/erased_render_asset.rs#L6-L42","documentation":"`PrepareAssetError::AsBindGroupError(AsBindGroupError)` is the hard-failure variant of render-asset preparation: building the bind group for an `AsBindGroup` material failed. The prepare system logs it via `error!` (\"{type} Bind group construction failed: {e}\") and the asset is skipped for that frame, so the material does not render until re-prepared.","triggerScenarios":"A material's `as_bind_group` errors during preparation: texture view/sample type not matching the declared `#[texture]` attributes (wrong dimension, non-filterable texture with a filtering sampler), or a binding not buildable on the current device.","commonSituations":"Declaring `dimension = \"2D\"` but assigning a cubemap/3D texture; using a filtering sampler on depth/unfilterable formats; bindless-required bindings on hardware without bindless support.","solutions":["Read the nested AsBindGroupError in the log line — it names the exact binding and mismatch","Make the `#[texture(dimension = ...)]` attributes match the actual textures you assign at runtime","Match sampler filtering to texture filterability (depth/unfilterable textures need non-filtering samplers) and check required device features"],"exampleFix":"// before\n#[texture(0, dimension = \"2D\")]\n#[sampler(1)]\nenv_map: Option<Handle<Image>>, // actually assigned a cubemap\n\n// after\n#[texture(0, dimension = \"Cubemap\")]\n#[sampler(1)]\nenv_map: Option<Handle<Image>>,","handlingStrategy":"try-catch","validationCode":"// before relying on a material, dry-run its bind group inputs\nlet layout_ok = device.limits().max_bind_groups >= expected_bindings;\nassert!(layout_ok, \"device cannot host this material layout\");","typeGuard":null,"tryCatchPattern":"// when implementing or wrapping as_bind_group for custom materials\nmatch material.as_bind_group(&layout, render_device, images) {\n    Ok(bind_group) => { /* use */ }\n    Err(AsBindGroupError::RetryNextUpdate) => { /* wait for next frame */ }\n    Err(e) => error!(\"material bind group failed: {e:?}\"),\n}","preventionTips":["Keep texture dimension attributes in sync with the textures you assign","Use non-filtering samplers for depth/unfilterable formats","Act on the first 'Bind group construction failed' log; later frames repeat the same failure"],"tags":["bevy","as-bind-group","material","bind-group","wgpu"],"backgroundTag":"bind-group-build-failed","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}