{"record":{"id":"d04a72f711c30c0d","repo":"bevyengine/bevy","slug":"failed-to-load-an-image-0","errorCode":null,"errorMessage":"failed to load an image: {0}","messagePattern":"failed to load an image: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2296,"sourceCode":"    /// Failed to load an image.\n    #[error(\"failed to load an image: {0}\")]\n    ImageError(#[from] image::ImageError),\n    /// Texture format isn't supported.\n    #[error(\"unsupported texture format: {0}\")]\n    UnsupportedTextureFormat(String),\n    /// 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","sourceCodeStart":2278,"sourceCodeEnd":2314,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2278-L2314","documentation":"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.","triggerScenarios":"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\")).","commonSituations":"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.","solutions":["Open the file in an image viewer or `image` CLI to confirm it decodes; if not, re-export from the source art.","Make sure the extension/mime you pass matches the actual bytes — or sniff with image::guess_format(&bytes) and pass ImageType::Format.","If the file was in transit, re-copy it in binary mode / re-pull from version control and compare checksums.","Catch TextureError::ImageError at the call site and fall back to a placeholder texture so one bad asset does not crash the app."],"exampleFix":"// before — file truncated, decode fails hard\nlet image = Image::from_buffer(&bytes, ImageType::Extension(\"png\"), formats, true, sampler, usage)?;\n\n// after — sniff the real format and fall back on decode failure\nlet fmt = image::guess_format(&bytes).ok()\n    .and_then(ImageFormat::from_image_crate_format)\n    .unwrap_or(ImageFormat::Png);\nlet image = Image::from_buffer(&bytes, ImageType::Format(fmt), formats, true, sampler, usage)\n    .unwrap_or_else(|_| placeholder_texture());","handlingStrategy":"try-catch","validationCode":"// cheap pre-check: the bytes must at least look like an image\nif image::guess_format(&bytes).is_err() {\n    warn!(\"bytes are not a recognizable image container\");\n    return;\n}","typeGuard":null,"tryCatchPattern":"match Image::from_buffer(&bytes, image_type, formats, true, sampler, usage) {\n    Ok(image) => { /* ... */ }\n    Err(TextureError::ImageError(e)) => {\n        error!(\"decode failed: {e}\"); // inspect e for truncation vs wrong format\n        use_placeholder()\n    }\n    Err(e) => error!(\"texture error: {e}\"),\n}","preventionTips":["Verify checksums when transferring texture files (git lfs fsck, binary-safe copies).","Sniff with image::guess_format before decoding so mismatched extensions are caught with a clearer error.","Never unwrap image loads; pair every load with a placeholder fallback path."],"tags":["bevy","image","decode","corrupt-file","rust"],"backgroundTag":"image-decode-failed","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"}