bevyengine/bevy · error · TextureAccessError

attempt to access texture with different dimension

Error message

attempt to access texture with different dimension

What it means

TextureAccessError::WrongDimension is returned when the pixel accessor's implied dimensionality does not match the Image's actual texture_descriptor.dimension (crates/bevy_image/src/image.rs:2250-2276). get_color_at requires TextureDimension::D2, get_color_at_1d requires D1, and get_color_at_3d requires D3 or D2 with depth_or_array_layers >= 2 (image.rs:1751-1803 and the set_* twins). Bevy throws it because coordinate meaning (is y a row or a layer?) is ambiguous across dimensions.

Source

Thrown at crates/bevy_image/src/image.rs:2282

    /// The texture's dimension was different than indicated by the accessor used.
    #[error("attempt to access texture with different dimension")]
    WrongDimension,
}

/// An error that occurs when loading a texture.
#[derive(Error, Debug)]
pub enum TextureError {
    /// Image MIME type is invalid.
    #[error("invalid image mime type: {0}")]
    InvalidImageMimeType(String),
    /// Image extension is invalid.
    #[error("invalid image extension: {0}")]
    InvalidImageExtension(String),
    /// Failed to load an image.
    #[error("failed to load an image: {0}")]
    ImageError(#[from] image::ImageError),
    /// Texture format isn't supported.
    #[error("unsupported texture format: {0}")]
    UnsupportedTextureFormat(String),
    /// Supercompression isn't supported.
    #[error("supercompression not supported: {0}")]
    SuperCompressionNotSupported(String),
    /// Failed to decompress an image.
    #[error("failed to decompress an image: {0}")]
    SuperDecompressionError(String),
    /// Invalid data.
    #[error("invalid data: {0}")]
    InvalidData(String),
    /// Transcode error.
    #[error("transcode error: {0}")]
    TranscodeError(String),
    /// Format requires transcoding.
    #[error("format requires transcoding: {0:?}")]
    FormatRequiresTranscodingError(TranscodeFormat),
    /// Only cubemaps with six faces are supported.
    #[error("only cubemaps with six faces are supported")]

View on GitHub (pinned to 221e52ae32)

Solutions

1. Match the accessor to image.texture_descriptor.dimension before calling: D1 -> get_color_at_1d, D2 -> get_color_at, D3 or layered D2 (depth_or_array_layers >= 2) -> get_color_at_3d.
2. For generic pixel reads use pixel_bytes(UVec3) which works for every dimension and only bounds-checks coordinates.
3. If you intended a plain 2D image but got D3/layered data, re-create the Image with TextureDimension::D2 and depth_or_array_layers: 1.

Example fix

// before — texture is a 3D volume texture
let color = image.get_color_at(x, y)?; // Err(WrongDimension)

// after — pick the accessor from the descriptor
let color = match image.texture_descriptor.dimension {
    TextureDimension::D1 => image.get_color_at_1d(x)?,
    TextureDimension::D2 if image.texture_descriptor.size.depth_or_array_layers < 2 => {
        image.get_color_at(x, y)?
    }
    _ => image.get_color_at_3d(x, y, 0)?,
};

// choose the accessor from the actual descriptor before touching pixels
let d = image.texture_descriptor.size.depth_or_array_layers;
match image.texture_descriptor.dimension {
    TextureDimension::D1 => { let _ = image.get_color_at_1d(x); }
    TextureDimension::D2 if d < 2 => { let _ = image.get_color_at(x, y); }
    _ => { let _ = image.get_color_at_3d(x, y, z); }
}

fn accessor_for(image: &Image) -> u8 {
    match (image.texture_descriptor.dimension, image.texture_descriptor.size.depth_or_array_layers) {
        (TextureDimension::D1, _) => 1,
        (TextureDimension::D2, 0..=1) => 2,
        _ => 3,
    }
}

let color = match image.get_color_at(x, y) {
    Err(TextureAccessError::WrongDimension) => image.get_color_at_3d(x, y, 0)?, // layered/3D
    result => result?,
};

When it happens

Trigger: Calling get_color_at/set_color_at (2D accessors) on a D1 or D3 image; calling get_color_at_1d on a 2D sprite texture; calling get_color_at_3d on a plain single-layer D2 image (depth_or_array_layers == 1 falls into the _ => Err(WrongDimension) arm at image.rs:1801).

Common situations: Reading pixels of a 3D noise texture or texture array with the plain 2D accessor; generic code that picks one accessor for all images; accessing a loaded sprite (single layer) with get_color_at_3d expecting z to work as 0.

Related errors

• unsupported texture format: {0:?}
• Could not load texture file: {0}
• Error reading image file {path}: {error}.
• Conversion into dynamic image not supported for {0:?}.
• Failed to convert into {0:?}.

AI-assisted analysis of bevyengine/bevy@221e52ae32 (2026-08-20). Data as JSON: /api/errors/e19811344d0f3679. Report an issue: GitHub.