{"record":{"id":"423026bfba225fcb","repo":"bevyengine/bevy","slug":"unsupported-texture-format-0-423026","errorCode":null,"errorMessage":"unsupported texture format: {0}","messagePattern":"unsupported texture format: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2299,"sourceCode":"    /// 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\")]\n    IncompleteCubemap,\n}\n\n/// The type of a raw image buffer.\n#[derive(Debug)]\npub enum ImageType<'a> {\n    /// The mime type of an image, for example `\"image/png\"`.\n    MimeType(&'a str),\n    /// The extension of an image file, for example `\"png\"`.\n    Extension(&'a str),\n    /// The direct format of the image\n    Format(ImageFormat),\n}\n\nimpl<'a> ImageType<'a> {\n    /// Attempts to detect the appropriate [`ImageFormat`] for this image type.\n    ///","sourceCodeStart":2281,"sourceCodeEnd":2317,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2281-L2317","documentation":"TextureError::UnsupportedTextureFormat (the String variant on TextureError) signals a texture format the loader cannot deliver, with a different cause per site: dds.rs:41 rejects formats the GPU does not support (\"Format not supported by this GPU\" — checked against CompressedImageFormats built from adapter features); ktx2.rs has dozens of VkFormat/sample combinations with no mapping (e.g. \"3-component formats not supported\"); basis.rs:35 rejects source formats that cannot transcode to the target; image.rs:1629 and image_loader.rs:221 hit formats with no image-crate decoder or no Bevy ImageFormat equivalent. It is the general 'cannot use this format here' error of the texture import pipeline.","triggerScenarios":"Loading a BC-compressed .dds on a GPU without TEXTURE_COMPRESSION_BC (common on Apple Silicon / mobile where only ASTC or ETC2 exist); a KTX2 with an exotic VkFormat; a Basis file whose basis_texture_format cannot transcode to the device's target format; enabling Guess-mode loading for bytes the image crate recognizes but Bevy has no ImageFormat for.","commonSituations":"Shipping one set of BC (Desktop) textures and running on macOS/Android; requesting adapter features in WgpuSettings that the physical device silently does not provide; disabling bevy features like dds/ktx2/basis-universal while still loading those files.","solutions":["Request the matching compression feature on the renderer (WgpuSettings.features |= Features::TEXTURE_COMPRESSION_BC / ETC2 / ASTC_LDR) so CompressedImageFormats includes your format.","Ship per-platform textures: BC for desktop, ASTC/ETC2 for mobile, and pick at load time.","Enable the container features on bevy/bevy_image (dds, ktx2, basis-universal) if the file never reaches its decoder.","Re-export the texture as plain PNG (uncompressed Rgba8UnormSrgb), which every device accepts, accepting the memory cost."],"exampleFix":"// before — BC dds fails on devices without BC support\nlet image = server.load(\"wall.dds\"); // TextureError: unsupported texture format: Format not supported by this GPU: Bc3...\n\n// after — request the feature and gate the asset by adapter support\nlet mut wgpu_settings = WgpuSettings::default();\nwgpu_settings.features |= wgpu::Features::TEXTURE_COMPRESSION_BC;\n// plus, at asset-selection time:\nlet supports_bc = compressed_formats_supports.contains(CompressedImageFormats::BC);\nlet path = if supports_bc { \"wall_bc.dds\" } else { \"wall_astc.ktx2\" };","handlingStrategy":"validation","validationCode":"// verify the format is in the adapter-supported set before loading containers\nlet supported = CompressedImageFormats::from_features(renderer_features);\nlet ok = supported.supports(TextureFormat::Bc3RgbaUnormSrgb);\nif !ok {\n    // choose the ASTC/ETC2 variant or uncompressed fallback asset\n}","typeGuard":"fn format_loadable(fmt: TextureFormat, supported: &CompressedImageFormats) -> bool {\n    let compressed = fmt.required_features();\n    compressed.is_empty() || supported.supports(fmt)\n}","tryCatchPattern":"match Image::from_buffer(&bytes, ty, formats, true, sampler, usage) {\n    Err(TextureError::UnsupportedTextureFormat(msg)) => {\n        warn!(\"{msg}; using uncompressed fallback\");\n        Image::from_buffer(&png_bytes, ImageType::Format(ImageFormat::Png), formats, true, sampler, usage)\n    }\n    result => result,\n}","preventionTips":["Request the compression features you rely on in WgpuSettings and assert they landed after adapter init.","Ship per-GPU texture variants (BC desktop, ASTC mobile) and select at load time.","Test on the lowest-end target device class, not just your dev GPU."],"tags":["bevy","texture","gpu-features","compressed-formats","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"}