bevyengine/bevy · error · TextureError

supercompression not supported: {0}

Error message

supercompression not supported: {0}

What it means

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.

Source

Thrown at crates/bevy_image/src/image.rs:2302

    /// Supercompression isn't supported.
    #[error("supercompression not supported: {0}")]
    SuperCompressionNotSupported(String),
    /// Failed to decompress an image.
    #[error("failed to decompress an image: {0}")]
    SuperDecompressionError(String),
    /// Invalid data.
    #[error("invalid data: {0}")]
    InvalidData(String),
    /// Transcode error.
    #[error("transcode error: {0}")]
    TranscodeError(String),
    /// Format requires transcoding.
    #[error("format requires transcoding: {0:?}")]
    FormatRequiresTranscodingError(TranscodeFormat),
    /// Only cubemaps with six faces are supported.
    #[error("only cubemaps with six faces are supported")]
    IncompleteCubemap,
}

/// The type of a raw image buffer.
#[derive(Debug)]
pub enum ImageType<'a> {
    /// The mime type of an image, for example `"image/png"`.
    MimeType(&'a str),
    /// The extension of an image file, for example `"png"`.
    Extension(&'a str),
    /// The direct format of the image
    Format(ImageFormat),
}

impl<'a> ImageType<'a> {
    /// Attempts to detect the appropriate [`ImageFormat`] for this image type.
    ///
    /// # Errors
    ///
    /// A [`TextureError`] will be returned if this image type is a MIME type or file extension for

View on GitHub (pinned to 221e52ae32)

Solutions

1. Enable the decompression backend on bevy_image/bevy: zlib (flate2) for ZLIB, zstd_rust or zstd_c for Zstandard.
2. Re-export the KTX2 without supercompression (toktx without --zstd/--zlib) — it is off by default.
3. 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.

Example fix

// before — KTX2 was exported with `toktx --zstd`
let image = server.load("sky.ktx2"); // SuperCompressionNotSupported("Zstandard")

// after — enable a zstd backend in Cargo.toml
// bevy = { version = "0.17", features = ["zstd_rust"] }
// or re-export without supercompression:
// toktx --bcmp sky.png -o sky.ktx2

// inspect the KTX2 supercompression scheme before handing bytes to the loader
// (ktx2 crate: header().supercompression_scheme)
if let Some(scheme) = ktx2.header().supercompression_scheme {
    if !matches!(scheme, SupercompressionScheme::ZLIB | SupercompressionScheme::Zstandard) {
        // re-export or reject the asset early
    }
}

match Image::from_buffer(&bytes, ImageType::Format(ImageFormat::Ktx2), formats, true, sampler, usage) {
    Err(TextureError::SuperCompressionNotSupported(s)) | Err(TextureError::SuperDecompressionError(s)) if s.contains("supercompression") => {
        load_uncompressed_fallback()
    }
    result => result,
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to decompress an image: {0}
• invalid image mime type: {0}
• invalid image extension: {0}
• invalid data: {0}
• format requires transcoding: {0:?}

AI-assisted analysis of bevyengine/bevy@221e52ae32 (2026-08-20). Data as JSON: /api/errors/7685fef7439ea0da. Report an issue: GitHub.