bevyengine/bevy · error · TextureError

failed to decompress an image: {0}

Error message

failed to decompress an image: {0}

What it means

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.

Source

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

    /// 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
    /// an unsupported or disabled format.
    pub fn to_image_format(&self) -> Result<ImageFormat, TextureError> {
        match self {

View on GitHub (pinned to 221e52ae32)

Solutions

1. Re-export the KTX2 without supercompression (default toktx output) to remove the decompression step entirely.
2. Verify the file is intact: compare checksums with the source, re-transfer in binary mode.
3. Make sure the matching backend feature is enabled: zlib (flate2) for ZLIB files, zstd_rust or zstd_c for Zstandard files.
4. If the file uses Lzma/BasisLZ schemes, re-create it with a supported scheme or plain levels.

Example fix

// before — zstd-supercompressed file, truncated in transit
let image = server.load("armor.ktx2"); // SuperDecompressionError("Failed to decompress Zstandard for mip 0: ...")

// after — re-export without supercompression
// toktx --bcmp armor.png -o armor.ktx2
let image = server.load("armor.ktx2");

match server.load("sky.ktx2") { /* handle via events instead: */ }
fn on_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {
    for ev in ev.read() {
        if let ImageLoaderError::FileTexture(fe) = &*ev.error {
            if let TextureError::SuperDecompressionError(m) = &fe.error {
                error!("{} needs re-export (scheme/decompress: {m})", fe.path);
            }
        }
    }
}

When it happens

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

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

Related errors

• supercompression not supported: {0}
• invalid data: {0}
• format requires transcoding: {0:?}
• Field name should exist
• Field name should be a valid tuple index

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