bevyengine/bevy · error · TextureAtlasBuilderError

cannot add texture to uninitialized atlas texture

Error message

cannot add texture to uninitialized atlas texture

What it means

TextureAtlasBuilderError::UninitializedAtlas — add_texture was called before the builder created the atlas texture, so there is no destination to copy into. Initialize/allocate the atlas (the builder creates it on first properly prepared add) before adding textures.

Source

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

};
use thiserror::Error;
use tracing::{debug, error, warn};
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,

View on GitHub (pinned to 396ca72708)

Solutions

1. Add at least one texture before operations that require an initialized atlas
2. Set the atlas texture format and size on the builder up front

When it happens

Trigger: Thrown at crates/bevy_image/src/texture_atlas_builder.rs:25 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/1476e1a3885b8aab. Report an issue: GitHub.