bevyengine/bevy · error · TextureAtlasBuilderError

texture access error: {0}

Error message

texture access error: {0}

What it means

Wrapper variant: an inner TextureAccessError occurred while reading the pixel data of an image being added to the atlas (e.g. out-of-bounds access while copying its region). The underlying error is the payload.

Source

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

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.
    format: TextureFormat,
    /// Enable automatic format conversion for textures if they are not in the atlas format.
    auto_format_conversion: bool,

View on GitHub (pinned to 396ca72708)

Solutions

1. Fix the underlying TextureAccessError (e.g. out-of-bounds access or unsupported texture format)
2. Inspect the wrapped error to identify the failing access and correct the image or access pattern

When it happens

Trigger: Thrown at crates/bevy_image/src/texture_atlas_builder.rs:31 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/724141746e1036ed. Report an issue: GitHub.