bevyengine/bevy · error · TextureAtlasBuilderError

could not pack textures into an atlas within the given bound

Error message

could not pack textures into an atlas within the given bounds

What it means

TextureAtlasBuilderError::NotEnoughSpace — rectangle-packing failed to place all submitted textures inside the atlas bin of the configured padding/p max size. Fires when total texture area plus padding exceeds the atlas dimensions; enlarge the atlas or reduce input texture sizes/count.

Source

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

use bevy_asset::{AssetId, RenderAssetUsages};
use bevy_math::{URect, UVec2};
use bevy_platform::collections::HashMap;
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

View on GitHub (pinned to 396ca72708)

Solutions

  1. Increase max_size on the TextureAtlasBuilder
  2. Reduce the number or size of textures added to the atlas
  3. Split the textures across multiple atlases
Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at crates/bevy_image/src/texture_atlas_builder.rs:19 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/94b1d25181506315. Report an issue: GitHub.