bevyengine/bevy · error · TextureError

failed to load an image: {0}

Error message

failed to load an image: {0}

What it means

TextureError::ImageError wraps an error from the `image` crate (via #[from] image::ImageError) and is raised at image.rs:1633 where Image::from_buffer calls reader.decode() on bytes routed through the generic image-crate path. It means the bytes were recognized as a decodable format but decoding itself failed — corrupt or truncated data, mismatched magic bytes, or an encoding variant the decoder rejects. Bevy re-exports it as a TextureError so all load failures share one type.

Source

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

    /// Failed to load an image.
    #[error("failed to load an image: {0}")]
    ImageError(#[from] image::ImageError),
    /// Texture format isn't supported.
    #[error("unsupported texture format: {0}")]
    UnsupportedTextureFormat(String),
    /// 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),
}

View on GitHub (pinned to 221e52ae32)

Solutions

1. Open the file in an image viewer or `image` CLI to confirm it decodes; if not, re-export from the source art.
2. Make sure the extension/mime you pass matches the actual bytes — or sniff with image::guess_format(&bytes) and pass ImageType::Format.
3. If the file was in transit, re-copy it in binary mode / re-pull from version control and compare checksums.
4. Catch TextureError::ImageError at the call site and fall back to a placeholder texture so one bad asset does not crash the app.

Example fix

// before — file truncated, decode fails hard
let image = Image::from_buffer(&bytes, ImageType::Extension("png"), formats, true, sampler, usage)?;

// after — sniff the real format and fall back on decode failure
let fmt = image::guess_format(&bytes).ok()
    .and_then(ImageFormat::from_image_crate_format)
    .unwrap_or(ImageFormat::Png);
let image = Image::from_buffer(&bytes, ImageType::Format(fmt), formats, true, sampler, usage)
    .unwrap_or_else(|_| placeholder_texture());

// cheap pre-check: the bytes must at least look like an image
if image::guess_format(&bytes).is_err() {
    warn!("bytes are not a recognizable image container");
    return;
}

match Image::from_buffer(&bytes, image_type, formats, true, sampler, usage) {
    Ok(image) => { /* ... */ }
    Err(TextureError::ImageError(e)) => {
        error!("decode failed: {e}"); // inspect e for truncation vs wrong format
        use_placeholder()
    }
    Err(e) => error!("texture error: {e}"),
}

When it happens

Trigger: Image::from_buffer on a PNG that is truncated mid-IDAT, a JPEG with unsupported color mode, or a file whose bytes do not match the supplied ImageType (a PNG renamed to .jpg and decoded with ImageType::Extension("jpg")).

Common situations: Partially downloaded or zero-byte image files; textures corrupted by a bad git LFS checkout or FTP transfer in ASCII mode; images exported by tools with unusual color profiles (16-bit TIFF, CMYK JPEG); hot-reload picking up a file mid-write.

Related errors

• Field name should exist
• Field name should be a valid tuple index
• invalid image mime type: {0}
• invalid image extension: {0}
• invalid data: {0}

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