{"record":{"id":"7685fef7439ea0da","repo":"bevyengine/bevy","slug":"supercompression-not-supported-0","errorCode":null,"errorMessage":"supercompression not supported: {0}","messagePattern":"supercompression not supported: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2302,"sourceCode":"    /// 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    ///\n    /// # Errors\n    ///\n    /// A [`TextureError`] will be returned if this image type is a MIME type or file extension for","sourceCodeStart":2284,"sourceCodeEnd":2320,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2284-L2320","documentation":"TextureError::SuperCompressionNotSupported (image.rs:2294-2295) is the declared error for a KTX2 file whose supercompression scheme this build cannot handle. In the current tree it has no construction sites — the KTX2 loader now reports unknown schemes as SuperDecompressionError(\"Unsupported supercompression scheme: ...\") (ktx2.rs:96-100) — so encountering this exact variant means an older Bevy or another producer of TextureError. Historically it fired when a KTX2 used ZLIB or Zstandard supercompression but the corresponding cargo feature (zlib/flate2, zstd_rust/zstd_c) was not enabled.","triggerScenarios":"On Bevy versions that construct it: loading a KTX2 exported with `toktx --zstd` or ZLIB supercompression in a build where bevy_image's zlib/flate2 or zstd features are off. In this tree the equivalent failure surfaces as SuperDecompressionError instead.","commonSituations":"Size-optimized KTX2 pipelines that enable supercompression by default; builds that trimmed bevy features; upgrading Bevy and finding the error message changed shape between releases.","solutions":["Enable the decompression backend on bevy_image/bevy: zlib (flate2) for ZLIB, zstd_rust or zstd_c for Zstandard.","Re-export the KTX2 without supercompression (toktx without --zstd/--zlib) — it is off by default.","If you see this variant on a recent Bevy, treat it as a legacy/version-mismatch signal and match on the whole TextureError enum, not this arm alone."],"exampleFix":"// before — KTX2 was exported with `toktx --zstd`\nlet image = server.load(\"sky.ktx2\"); // SuperCompressionNotSupported(\"Zstandard\")\n\n// after — enable a zstd backend in Cargo.toml\n// bevy = { version = \"0.17\", features = [\"zstd_rust\"] }\n// or re-export without supercompression:\n// toktx --bcmp sky.png -o sky.ktx2","handlingStrategy":"fallback","validationCode":"// inspect the KTX2 supercompression scheme before handing bytes to the loader\n// (ktx2 crate: header().supercompression_scheme)\nif let Some(scheme) = ktx2.header().supercompression_scheme {\n    if !matches!(scheme, SupercompressionScheme::ZLIB | SupercompressionScheme::Zstandard) {\n        // re-export or reject the asset early\n    }\n}","typeGuard":null,"tryCatchPattern":"match Image::from_buffer(&bytes, ImageType::Format(ImageFormat::Ktx2), formats, true, sampler, usage) {\n    Err(TextureError::SuperCompressionNotSupported(s)) | Err(TextureError::SuperDecompressionError(s)) if s.contains(\"supercompression\") => {\n        load_uncompressed_fallback()\n    }\n    result => result,\n}","preventionTips":["Export KTX2 without supercompression unless you enable the zlib/zstd cargo features in every build profile.","Match on the whole TextureError enum — this variant is not constructed by current Bevy and indicates a version skew."],"tags":["bevy","ktx2","supercompression","feature-gate","rust"],"backgroundTag":"unsupported-compression-scheme","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"}