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.

[dubrowgn]

I am also seeing this crash, and I also confirmed my image is actually loaded (by dumping image data with dbg!(image)) before I spawn any TilemapChunks.

I'm using bevy v0.17.2, vulkan, Linux Mint 22.2, and an RTX3070. I tried setting WGPU_BACKEND=gl, but wgpu claims it can't find a GPU that way.

[dubrowgn]

For the non-fallback case, the critical line is:

image.reinterpret_stacked_2d_as_array(4);

Which avoids the crash, but unfortunately imposes some rather significant limitations on the layout of the tilemap image.

[Duke02]

Also getting this error and crash. Using the tilemap below/attached. Tilemap is supposed to be a 16x80 (width x height in pixels) image with 5 tiles. Rotating it to be horizontal rather than vertical also causes it to crash. Code is as follows (similar to everyone else's):

let chunk_size = UVec2::new(1, 5);
    let tile_display_size = UVec2::splat(16);
    let tile_data: Vec<Option<TileData>> = (0..chunk_size.element_product() as u16)
        .map(|i| Some(TileData {
            tileset_index: i,
            color: Color::BLACK,
            visible: true,
        }))
        .collect();

    let image = assets.load("tilemap.png");
    info!("{image:?}");

    commands.spawn((
        TilemapChunk {
            chunk_size,
            tile_display_size,
            tileset: image,

            alpha_mode: AlphaMode2d::Opaque,
        },
        TilemapChunkTileData(tile_data),
    ));

I made sure that my image variable is printed out. It's printed out as StrongHandle<Image>{ id: Index(AssetIndex { generation: 0, index: 7 }), path: Some(tilemap.png) }. Attempted above env var idea of WGPU_BACKEND=gl and got the same crash of cannot find GPU. vulkaninfo prints that I have some features enabled (can provide full list if needed). I have commented out the TilemapChunkTileData(tile_data) portion of my commands.spawn code and my code is able to work (albeit with nothing rendered as I'm trying to fix this issue of loading my assets before actually rendering said assets. I imagine I will be unable to render assets I don't have so haven't tested that). Below my tilemap is my neofetch output for system information (Pop!OS 22.04LTS, NVIDIA GPU, Intel CPU with Integrated Graphics, GNOME DE). Bevy dependency listing is bevy = { version = "0.17.2", features = ["wayland", "webgl2"] }. Thanks!