Crash when tilemap is created without a tileset image

[IWonderWhatThisAPIDoes]

Bevy version and features

0.17.2, default features

What you did

Code is a minimized version of the Tilemap example (https://bevy.org/examples/2d-rendering/tilemap-chunk/). The error occurs when a tilemap is spawned, but not given an image handle for its tileset, so the default image handle is used.

use bevy::{
    prelude::*,
    sprite_render::{TileData, TilemapChunk, TilemapChunkTileData},
};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands, assets: Res<AssetServer>) {
    let chunk_size = UVec2::splat(64);
    let tile_data: Vec<Option<TileData>> =
        vec![Some(TileData::from_tileset_index(0)); chunk_size.element_product() as usize];

    commands.spawn((
        TilemapChunk {
            chunk_size,
            tile_display_size: UVec2::splat(8),
            // Omiting this line causes the error
            tileset: assets.load("textures/array_texture.png"),
            ..default()
        },
        TilemapChunkTileData(tile_data),
    ));

    commands.spawn(Camera2d);
}

Observed behavior

thread 'Compute Task Pool (1)' panicked at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:1195:26:
wgpu error: Validation Error

Caused by:
  In Device::create_bind_group, label = 'TilemapChunkMaterial'
    Texture binding 0 expects dimension = D2Array, but given a view with dimension = D2


stack backtrace:
   0: std::panicking::begin_panic_handler
             at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\std\src\panicking.rs:697
   1: core::panicking::panic_fmt
             at /rustc/29483883eed69d5fb4db01964cdf2af4d86e9cb2/library\core\src\panicking.rs:75
   2: wgpu::backend::wgpu_core::default_error_handler
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:659
   3: wgpu::backend::wgpu_core::ErrorSinkRaw::handle_error
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:643
   4: wgpu::backend::wgpu_core::ContextWgpuCore::handle_error_inner
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:298
   5: wgpu::backend::wgpu_core::ContextWgpuCore::handle_error<enum2$<wgpu_core::binding_model::CreateBindGroupError> >
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:311
   6: wgpu::backend::wgpu_core::impl$12::create_bind_group
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\backend\wgpu_core.rs:1195
   7: wgpu::api::device::Device::create_bind_group
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wgpu-26.0.1\src\api\device.rs:220
   8: bevy_render::renderer::render_device::RenderDevice::create_bind_group<enum2$<core::option::Option<ref$<str$> > > >
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_render-0.17.2\src\renderer\render_device.rs:154
   9: bevy_render::render_resource::bind_group::AsBindGroup::as_bind_group<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChunkMaterial>
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_render-0.17.2\src\render_resource\bind_group.rs:548
  10: bevy_sprite_render::mesh2d::material::impl$21::prepare_asset<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChunkMaterial>
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_sprite_render-0.17.2\src\mesh2d\material.rs:986
  11: bevy_render::render_asset::prepare_assets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChunkMaterial> >
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_render-0.17.2\src\render_asset.rs:398
  12: core::ops::function::FnMut::call_mut<void (*)(bevy_ecs::change_detection::ResMut<bevy_render::render_asset::ExtractedAssets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChunkMate
             at C:\Users\~\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\ops\function.rs:166
  13: core::ops::function::impls::impl$3::call_mut<tuple$<bevy_ecs::change_detection::ResMut<bevy_render::render_asset::ExtractedAssets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChu
             at C:\Users\~\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\src\rust\library\core\src\ops\function.rs:294
  14: bevy_ecs::system::function_system::impl$42::run::call_inner<tuple$<>,bevy_ecs::change_detection::ResMut<bevy_render::render_asset::ExtractedAssets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_mat
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_ecs-0.17.2\src\system\function_system.rs:926
  15: bevy_ecs::system::function_system::impl$42::run<tuple$<>,void (*)(bevy_ecs::change_detection::ResMut<bevy_render::render_asset::ExtractedAssets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_materi
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_ecs-0.17.2\src\system\function_system.rs:929
  16: bevy_ecs::system::function_system::impl$12::run_unsafe<void (*)(bevy_ecs::change_detection::ResMut<bevy_render::render_asset::ExtractedAssets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material
             at C:\Users\~\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\bevy_ecs-0.17.2\src\system\function_system.rs:711
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
Encountered a panic in system `bevy_render::render_asset::prepare_assets<bevy_sprite_render::mesh2d::material::PreparedMaterial2d<bevy_sprite_render::tilemap_chunk::tilemap_chunk_material::TilemapChunkMaterial>>`!

Expected behavior

I believe an error like this should not crash the app, but should simply not render anything. Specifically, if an image handle is provided, the app does not crash, even if the image file does not actually exist.

Additional information

It seems the default image has a dimension that is incompatible with a tileset image, which the bind group violently rejects. On the other hand, when the asset fails to load because the file does not exist, the app does not crash because prepare_assets does not run at all.

[Badgerup1510]

Adding to this. I am also replicating the tilemap example but using an image as expected by the example. This causes the same error experience by the original poster. I thought I should add this as I am experiencing it with a valid image and experiencing the same error which was not mentioned in the post.

Code:

fn spawn_chunk(
mut commands: Commands,
assets: Res,
) {
let chunk_size = UVec2::new(16, 16);
let mut rng = rand::rng();

let tile_data: Vec<Option<TileData>> = (0..chunk_size.element_product())
    .map(|_| rng.random_range(0..5))
    .map(|i| {
        if i == 0 {
            None
        } else {
            Some(TileData::from_tileset_index(i - 1))
        }
    })
    .collect();

commands.spawn((
        TilemapChunk {
            tileset: assets.load("sprites/basic_tilemap.png"),
            chunk_size,
            tile_display_size: UVec2::new(16, 16),
            ..default()
        },
        TilemapChunkTileData(tile_data),
));

}

Error:

ERROR wgpu::backend::wgpu_core: Handling wgpu errors as fatal by default

thread 'Compute Task Pool (5)' panicked at /home/users/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/wgpu-26.0.1/src/backend/wgpu_core.rs:1195:26:
wgpu error: Validation Error

Caused by:
In Device::create_bind_group, label = 'TilemapChunkMaterial'
Texture binding 0 expects dimension = D2Array, but given a view with dimension = D2

[IWonderWhatThisAPIDoes]

I did a little digging in the stack trace, and eventually reached wgpu-26.0.1\src\backend\wgpu_core.rs:659:

fn default_error_handler(err: crate::Error) {
    log::error!("Handling wgpu errors as fatal by default");
    panic!("wgpu error: {err}\n");
}

I figured out how to override it so it does not crash the app (not that I would want to do that in production code):

fn startup(Res<RenderDevice>) {
    render.wgpu_device().on_uncaptured_error(Box::new(|e| error!("{e}")));
}

For completeness' sake, this is the full error it yields

2025-10-11T09:20:36.772365Z ERROR project: Validation Error

Caused by:
  In Device::create_bind_group, label = 'TilemapChunkMaterial'
    Texture binding 0 expects dimension = D2Array, but given a view with dimension = D2

Debug dump:

Validation {
    source: ContextError {
        fn_ident: "Device::create_bind_group",
        source: InvalidTextureDimension {
            binding: 0,
            layout_dimension: D2Array,
            view_dimension: D2
        },
        label: "TilemapChunkMaterial"
    },
    description: "Validation Error\n\nCaused by:\n  In Device::create_bind_group, label = 'TilemapChunkMaterial'\n    Texture binding 0 expects dimension = D2Array, but given a view with dimension = D2\n"
}

Catching and discarding it will cause the wgpu to throw a different error on every frame:

Caused by:
  In a CommandEncoder
    In a set_bind_group command
      BindGroup with 'TilemapChunkMaterial' label is invalid

Validation {
    source: ContextError {
        fn_ident: "Queue::submit",
        source: CommandEncoder(RenderPass(RenderPassError {
            scope: SetBindGroup,
            inner: InvalidResource(InvalidResourceError(ResourceErrorIdent {
                type: "BindGroup",
                label: "TilemapChunkMaterial"
            }))
        })),
        label: ""
    },
    description: "Validation Error\n\nCaused by:\n In Queue::submit\n In a set_bind_group command\n BindGroup with 'TilemapChunkMaterial' label is invalid\n"
}

[grind086]

It looks like it's not selecting the appropriate FallbackImage, but I'm not sure why or where it could even be doing that. Everywhere I've looked selects based on the texture dimension, as it should.