{"record":{"id":"e19811344d0f3679","repo":"bevyengine/bevy","slug":"attempt-to-access-texture-with-different-dimension","errorCode":null,"errorMessage":"attempt to access texture with different dimension","messagePattern":"attempt to access texture with different dimension","errorType":"exception","errorClass":"TextureAccessError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2282,"sourceCode":"    /// The texture's dimension was different than indicated by the accessor used.\n    #[error(\"attempt to access texture with different dimension\")]\n    WrongDimension,\n}\n\n/// An error that occurs when loading a texture.\n#[derive(Error, Debug)]\npub enum TextureError {\n    /// Image MIME type is invalid.\n    #[error(\"invalid image mime type: {0}\")]\n    InvalidImageMimeType(String),\n    /// Image extension is invalid.\n    #[error(\"invalid image extension: {0}\")]\n    InvalidImageExtension(String),\n    /// Failed to load an image.\n    #[error(\"failed to load an image: {0}\")]\n    ImageError(#[from] image::ImageError),\n    /// Texture format isn't supported.\n    #[error(\"unsupported texture format: {0}\")]\n    UnsupportedTextureFormat(String),\n    /// Supercompression isn't supported.\n    #[error(\"supercompression not supported: {0}\")]\n    SuperCompressionNotSupported(String),\n    /// Failed to decompress an image.\n    #[error(\"failed to decompress an image: {0}\")]\n    SuperDecompressionError(String),\n    /// Invalid data.\n    #[error(\"invalid data: {0}\")]\n    InvalidData(String),\n    /// Transcode error.\n    #[error(\"transcode error: {0}\")]\n    TranscodeError(String),\n    /// Format requires transcoding.\n    #[error(\"format requires transcoding: {0:?}\")]\n    FormatRequiresTranscodingError(TranscodeFormat),\n    /// Only cubemaps with six faces are supported.\n    #[error(\"only cubemaps with six faces are supported\")]","sourceCodeStart":2264,"sourceCodeEnd":2300,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2264-L2300","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","For generic pixel reads use pixel_bytes(UVec3) which works for every dimension and only bounds-checks coordinates.","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."],"exampleFix":"// before — texture is a 3D volume texture\nlet color = image.get_color_at(x, y)?; // Err(WrongDimension)\n\n// after — pick the accessor from the descriptor\nlet color = match image.texture_descriptor.dimension {\n    TextureDimension::D1 => image.get_color_at_1d(x)?,\n    TextureDimension::D2 if image.texture_descriptor.size.depth_or_array_layers < 2 => {\n        image.get_color_at(x, y)?\n    }\n    _ => image.get_color_at_3d(x, y, 0)?,\n};","handlingStrategy":"validation","validationCode":"// choose the accessor from the actual descriptor before touching pixels\nlet d = image.texture_descriptor.size.depth_or_array_layers;\nmatch image.texture_descriptor.dimension {\n    TextureDimension::D1 => { let _ = image.get_color_at_1d(x); }\n    TextureDimension::D2 if d < 2 => { let _ = image.get_color_at(x, y); }\n    _ => { let _ = image.get_color_at_3d(x, y, z); }\n}","typeGuard":"fn accessor_for(image: &Image) -> u8 {\n    match (image.texture_descriptor.dimension, image.texture_descriptor.size.depth_or_array_layers) {\n        (TextureDimension::D1, _) => 1,\n        (TextureDimension::D2, 0..=1) => 2,\n        _ => 3,\n    }\n}","tryCatchPattern":"let color = match image.get_color_at(x, y) {\n    Err(TextureAccessError::WrongDimension) => image.get_color_at_3d(x, y, 0)?, // layered/3D\n    result => result?,\n};","preventionTips":["Write one pixel-read helper that dispatches on texture_descriptor.dimension instead of calling accessors ad hoc.","For generic code prefer pixel_bytes(UVec3), which works for all dimensions.","Assert the dimension in debug builds when a function requires a specific layout."],"tags":["bevy","texture","dimension","pixel-access","rust"],"backgroundTag":"dimension-mismatch","analyzedSha":"221e52ae323febfd399bd7d067918fc43648cfb3","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}