{"record":{"id":"1bdf569f99b80fc2","repo":"bevyengine/bevy","slug":"unsupported-texture-format-0","errorCode":null,"errorMessage":"unsupported texture format: {0:?}","messagePattern":"unsupported texture format: (.+?)","errorType":"exception","errorClass":"TextureAccessError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2272,"sourceCode":"    /// Most often this is returned when attempting to access pixel data of compressed textures.\n    #[error(\"unsupported texture format: {0:?}\")]\n    UnsupportedTextureFormat(TextureFormat),\n    /// Attempted to access the data of an image before it was initialized, or after it was moved\n    /// to the GPU.\n    ///\n    /// See [`RenderAssetUsages`] for more information about when an asset's data is moved, and\n    /// how to retain it if necessary.\n    #[error(\"image data is not initialized\")]\n    Uninitialized,\n    /// 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.","sourceCodeStart":2254,"sourceCodeEnd":2290,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2254-L2290","documentation":"TextureAccessError::UnsupportedTextureFormat is returned by bevy_image's CPU pixel accessors (Image::get_color_at*, set_color_at*, pixel_bytes, pixel_bytes_mut, pixel_data_offset) when the TextureFormat has no fixed per-pixel byte size. The gate is TextureFormat::pixel_size (crates/bevy_image/src/image.rs:2354), which errors for any format whose block dimensions are not (1,1) — every block-compressed format (Bc*, Etc2*, Astc*). The color accessors additionally reject formats that cannot decode into Color, such as non-byte-aligned (Rg11b10-like) and signed-integer formats. Bevy throws it because per-pixel addressing is undefined for block-compressed data.","triggerScenarios":"Calling image.get_color_at(x, y) / get_color_at_1d / get_color_at_3d / set_color_at* on an Image whose texture_descriptor.format is block-compressed (e.g. Bc1RgbaUnorm loaded from a .dds/.ktx2), or calling pixel_bytes/pixel_bytes_mut/Image::convert on such an image. The crate's own test (image.rs:2528, compressed_texture_format_is_reported_correctly) shows get_color_at on Bc1RgbaUnorm returning exactly this variant.","commonSituations":"Loading a compressed .ktx2/.dds/.basis texture and reading pixels for a minimap, picking, or runtime atlas packing; calling Image::convert on GPU-compressed data; indexing pixel data of an image asset after the ImageLoader selected a BC/ASTC format supported by the adapter.","solutions":["Keep an uncompressed companion asset (e.g. the source PNG) for any texture you must read or write on the CPU, and do pixel access only on that copy.","Check image.is_compressed() or image.texture_descriptor.format.pixel_size().is_err() before every accessor call and skip/log instead of unwrapping.","If you control the pipeline, export the texture uncompressed (PNG/Rgba8UnormSrgb) instead of BC/ETC2/ASTC.","As a last resort, decode block-compressed data yourself with a CPU BC/ETC2/ASTC decoder crate before doing byte-level access."],"exampleFix":"// before — image came from a .ktx2, format is Bc7RgbaUnormSrgb\nlet color = image.get_color_at(10, 20)?; // Err(UnsupportedTextureFormat(Bc7RgbaUnormSrgb))\n\n// after — read from the uncompressed source copy you shipped next to it\nlet color = if image.is_compressed() {\n    uncompressed_source.get_color_at(10, 20)?\n} else {\n    image.get_color_at(10, 20)?\n};","handlingStrategy":"validation","validationCode":"use bevy_image::{Image, TextureFormatPixelInfo};\n\nfn can_read_pixels(image: &Image) -> bool {\n    !image.is_compressed() && image.texture_descriptor.format.pixel_size().is_ok()\n}\n\n// before any accessor:\nif can_read_pixels(&image) {\n    let color = image.get_color_at(x, y)?;\n}","typeGuard":"fn pixel_readable(image: &Image) -> bool {\n    use bevy_image::TextureFormatPixelInfo;\n    !image.is_compressed()\n        && image.texture_descriptor.format.pixel_size().is_ok()\n        && image.data.is_some()\n}","tryCatchPattern":"match image.get_color_at(x, y) {\n    Ok(color) => { /* use color */ }\n    Err(TextureAccessError::UnsupportedTextureFormat(fmt)) => {\n        warn!(\"no CPU pixel access for compressed format {fmt:?}\");\n    }\n    Err(TextureAccessError::Uninitialized) => { /* data is GPU-only */ }\n    Err(TextureAccessError::OutOfBounds { x, y, z }) => { /* clamp coords */ }\n    Err(TextureAccessError::WrongDimension) => { /* wrong accessor */ }\n}","preventionTips":["Ship an uncompressed PNG companion for every texture you read pixels from at runtime.","Route all pixel access through one helper that checks is_compressed() first.","Add a CI test that reads pixel (0,0) from every image asset to catch compressed/uninitialized sources early."],"tags":["bevy","texture","compressed-formats","pixel-access","rust"],"backgroundTag":"unsupported-texture-format","analyzedSha":"221e52ae323febfd399bd7d067918fc43648cfb3","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T20:17:18.057Z"}