bevyengine/bevy · error · TextureError

invalid data: {0}

Error message

invalid data: {0}

What it means

TextureError::InvalidData is the malformed-container error of the specialized loaders. It is raised when the KTX2 header cannot be parsed (ktx2.rs:36, "Failed to parse ktx2 file"), when the DDS reader fails (dds.rs:27, "Failed to parse DDS file"), and throughout basis.rs for invalid checksums (line 17, debug builds), invalid headers (20), missing image info (24), modulo-6 cubemap-array violations (49) and inconsistent mip level counts (72). It means the file is not a structurally valid instance of its claimed container format.

Source

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

    /// 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 {
            ImageType::MimeType(mime_type) => ImageFormat::from_mime_type(mime_type)
                .ok_or_else(|| TextureError::InvalidImageMimeType(mime_type.to_string())),
            ImageType::Extension(extension) => ImageFormat::from_extension(extension)

View on GitHub (pinned to 221e52ae32)

Solutions

1. Regenerate the file with a known-good tool: toktx for KTX2, texconv/compressonator for DDS, the official basis_universal encoder for .basis.
2. Verify the file is really the format its extension claims (first bytes: KTX2 magic 'KTX 20\xBB\r\n', 'DDS ', '\xAB BASIS').
3. Re-transfer/re-checkout the file in binary mode and compare hashes against the source.
4. Isolate the bad asset by loading files individually until the loader names the culprit path.

Example fix

// before — a KTX2 v1 file renamed to .ktx2
let image = server.load("noise.ktx2"); // InvalidData("Failed to parse ktx2 file: ...")

// after — convert to a real KTX2 v2 with toktx
// toktx --bcmp noise.png -o noise.ktx2
let image = server.load("noise.ktx2");

// cheap container sniff before loading
fn looks_like_ktx2(bytes: &[u8]) -> bool {
    bytes.starts_with(b"\xABKTX 20\xBB\r\n\x1A\n")
}
fn looks_like_dds(bytes: &[u8]) -> bool {
    bytes.starts_with(b"DDS ")
}

match Image::from_buffer(&bytes, ImageType::Format(ImageFormat::Ktx2), formats, true, sampler, usage) {
    Err(TextureError::InvalidData(msg)) => {
        error!("malformed container: {msg}"); // regenerate with toktx/texconv/basisu
        use_placeholder()
    }
    result => result,
}

When it happens

Trigger: A .dds file with a corrupted/odd header from an unusual exporter; a KTX2 v1 file renamed to .ktx2; a .basis file that failed checksum validation in a debug build; any container whose bytes were truncated or shuffled.

Common situations: Hand-edited or script-mangled texture files; KTX2/DDS produced by niche tools that emit non-conformant headers; assets corrupted by version-control line-ending rewriting on Windows; downloaded texture packs with broken files.

Related errors

• format requires transcoding: {0:?}
• failed to load an image: {0}
• supercompression not supported: {0}
• failed to decompress an image: {0}
• only cubemaps with six faces are supported

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