{"record":{"id":"7734c984bad85b3d","repo":"bevyengine/bevy","slug":"failed-to-decompress-an-image-0","errorCode":null,"errorMessage":"failed to decompress an image: {0}","messagePattern":"failed to decompress an image: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2305,"sourceCode":"    /// 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    ///\n    /// # Errors\n    ///\n    /// A [`TextureError`] will be returned if this image type is a MIME type or file extension for\n    /// an unsupported or disabled format.\n    pub fn to_image_format(&self) -> Result<ImageFormat, TextureError> {\n        match self {","sourceCodeStart":2287,"sourceCodeEnd":2323,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2287-L2323","documentation":"TextureError::SuperDecompressionError is raised inside ktx2_buffer_to_image (crates/bevy_image/src/ktx2.rs:62, 75, 78, 90, 97, 216) when a KTX2 file's mip levels are supercompressed and decompression fails: flate2 for ZLIB, ruzstd or the C zstd binding for Zstandard, each wrapping its io/decode error with the scheme and mip index; the catch-all arm at ktx2.rs:97 also maps unknown schemes (e.g. Lzma, BasisLz used without UASTC/ETC1S handling) to this variant. It means the container parsed but its level payloads could not be expanded.","triggerScenarios":"Loading a KTX2 written with `toktx --zstd` or ZLIB whose level data is truncated or corrupted; a KTX2 using an unsupported supercompression scheme (ktx2.rs:96-100); a build where the wrong zstd backend feature was chosen for the file's scheme.","commonSituations":"Truncated texture downloads; texture files corrupted in transit or by merge tools; switching a texture pipeline to supercompressed output while the runtime build lacks flate2/zstd features.","solutions":["Re-export the KTX2 without supercompression (default toktx output) to remove the decompression step entirely.","Verify the file is intact: compare checksums with the source, re-transfer in binary mode.","Make sure the matching backend feature is enabled: zlib (flate2) for ZLIB files, zstd_rust or zstd_c for Zstandard files.","If the file uses Lzma/BasisLZ schemes, re-create it with a supported scheme or plain levels."],"exampleFix":"// before — zstd-supercompressed file, truncated in transit\nlet image = server.load(\"armor.ktx2\"); // SuperDecompressionError(\"Failed to decompress Zstandard for mip 0: ...\")\n\n// after — re-export without supercompression\n// toktx --bcmp armor.png -o armor.ktx2\nlet image = server.load(\"armor.ktx2\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match server.load(\"sky.ktx2\") { /* handle via events instead: */ }\nfn on_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {\n    for ev in ev.read() {\n        if let ImageLoaderError::FileTexture(fe) = &*ev.error {\n            if let TextureError::SuperDecompressionError(m) = &fe.error {\n                error!(\"{} needs re-export (scheme/decompress: {m})\", fe.path);\n            }\n        }\n    }\n}","preventionTips":["Default your toktx exports to no supercompression unless memory budgets require it.","Enable zlib (flate2) and zstd_rust/zstd_c features consistently across dev/release profiles.","Checksum KTX2 assets at build time so corrupted files fail in CI, not on player devices."],"tags":["bevy","ktx2","supercompression","decompression","rust"],"backgroundTag":"decompression-failed","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"}