bevyengine/bevy · error · DynamicTextureAtlasBuilderError

Couldn't allocate space to add the image requested

Error message

Couldn't allocate space to add the image requested

What it means

DynamicTextureAtlasBuilderError::FailedToAllocateSpace: the atlas allocator (guillotiere) could not find free space for the new texture within the current atlas size — the atlas is effectively full or too fragmented.

Source

Thrown at crates/bevy_image/src/dynamic_texture_atlas_builder.rs:12

use crate::{Image, TextureAccessError, TextureAtlasLayout, TextureFormatPixelInfo as _};
use bevy_asset::RenderAssetUsages;
use bevy_math::{URect, UVec2};
use guillotiere::{size2, Allocation, AtlasAllocator};
use thiserror::Error;

/// An error produced by [`DynamicTextureAtlasBuilder`] when trying to add a new
/// texture to a [`TextureAtlasLayout`].
#[derive(Debug, Error)]
pub enum DynamicTextureAtlasBuilderError {
    /// Unable to allocate space within the atlas for the new texture
    #[error("Couldn't allocate space to add the image requested")]
    FailedToAllocateSpace,
    /// 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),
}

/// Helper utility to update [`TextureAtlasLayout`] on the fly.
///
/// Helpful in cases when texture is created procedurally,
/// e.g: in a font glyph [`TextureAtlasLayout`], only add the [`Image`] texture for letters to be rendered.
pub struct DynamicTextureAtlasBuilder {
    atlas_allocator: AtlasAllocator,

View on GitHub (pinned to 396ca72708)

Solutions

1. Grow the atlas (increase initial size / enable resizing in DynamicTextureAtlasBuilder)
2. Pad/grow the atlas with more empty space before adding
3. Fail gracefully and let the caller create a new atlas page

When it happens

Trigger: Thrown at crates/bevy_image/src/dynamic_texture_atlas_builder.rs:12 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/57401eac04ff7c3c. Report an issue: GitHub.