bevyengine/bevy · error · TextureAtlasBuilderError

cannot add uninitialized texture to atlas

Error message

cannot add uninitialized texture to atlas

What it means

TextureAtlasBuilderError::NoTextureData — the Image being added has no CPU pixel data (data is None), so its contents cannot be copied into the atlas. This happens for GPU-resident images created with render-only RenderAssetUsages; supply an image with main-world data.

Source

Thrown at crates/bevy_image/src/texture_atlas_builder.rs:28

use wgpu_types::{Extent3d, TextureDimension, TextureFormat};

use crate::{Image, TextureAccessError, TextureFormatPixelInfo};
use crate::{TextureAtlasLayout, TextureAtlasSources};

/// Errors returned by [`TextureAtlasBuilder`].
#[derive(Debug, Error)]
pub enum TextureAtlasBuilderError {
    /// The atlas texture wasn't large enough to fit the texture
    #[error("could not pack textures into an atlas within the given bounds")]
    NotEnoughSpace,
    /// Attempted to add a texture with a different format
    #[error("added a texture with the wrong format in an atlas")]
    WrongFormat,
    /// Attempted to add a texture to an uninitialized atlas
    #[error("cannot add texture to uninitialized atlas texture")]
    UninitializedAtlas,
    /// Attempted to add an uninitialized texture to an atlas
    #[error("cannot add uninitialized texture to atlas")]
    UninitializedSourceTexture,
    /// A texture access error occurred
    #[error("texture access error: {0}")]
    TextureAccess(#[from] TextureAccessError),
}

#[derive(Debug)]
#[must_use]
/// A builder which is used to create a texture atlas from many individual
/// sprites.
pub struct TextureAtlasBuilder<'a> {
    /// Collection of texture's asset id (optional) and image data to be packed into an atlas
    textures_to_place: Vec<(Option<AssetId<Image>>, &'a Image)>,
    /// The initial atlas size in pixels.
    initial_size: UVec2,
    /// The absolute maximum size of the texture atlas in pixels.
    max_size: UVec2,
    /// The texture format for the textures that will be loaded in the atlas.

View on GitHub (pinned to 396ca72708)

Solutions

1. Ensure the image asset is fully loaded and has pixel data before adding it to the atlas
2. Skip uninitialized images during atlas construction

When it happens

Trigger: Thrown at crates/bevy_image/src/texture_atlas_builder.rs:28 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/27097450e6dd33d7. Report an issue: GitHub.