bevyengine/bevy · error · TextureAtlasBuilderError

added a texture with the wrong format in an atlas

Error message

added a texture with the wrong format in an atlas

What it means

TextureAtlasBuilderError::WrongFormat — a texture was added whose TextureFormat differs from the format already established for the atlas. All images packed into one atlas must share a single TextureFormat; re-encode the offending image before adding.

Source

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

use rectangle_pack::{
    contains_smallest_box, pack_rects, volume_heuristic, GroupedRectsToPlace, PackedLocation,
    RectToInsert, TargetBin,
};
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

View on GitHub (pinned to 396ca72708)

Solutions

1. Convert added textures to the atlas's texture format before adding them
2. Create a separate atlas for the differently-formatted texture
3. Set the desired format on the builder before adding any textures

When it happens

Trigger: Thrown at crates/bevy_image/src/texture_atlas_builder.rs:22 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/5674205675e42a81. Report an issue: GitHub.