{"record":{"id":"2d9a88ed947d4d47","repo":"bevyengine/bevy","slug":"invalid-image-extension-0","errorCode":null,"errorMessage":"invalid image extension: {0}","messagePattern":"invalid image extension: (.+?)","errorType":"exception","errorClass":"TextureError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image.rs","lineNumber":2293,"sourceCode":"    /// Image extension is invalid.\n    #[error(\"invalid image extension: {0}\")]\n    InvalidImageExtension(String),\n    /// 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","sourceCodeStart":2275,"sourceCodeEnd":2311,"githubUrl":"https://github.com/bevyengine/bevy/blob/221e52ae323febfd399bd7d067918fc43648cfb3/crates/bevy_image/src/image.rs#L2275-L2311","documentation":"TextureError::InvalidImageExtension is returned by ImageType::to_image_format (crates/bevy_image/src/image.rs:2335-2336) when ImageFormat::from_extension cannot map the extension string to a format. from_extension (image.rs:487) knows a fixed, feature-gated list (png, jpg|jpeg, dds, ktx2, exr, hdr, qoi, ff|farbfeld, basis, ico, gif, bmp, tga, webp, tiff, pam|pbm|pgm|ppm), lowercased before matching; anything else — or a format whose cargo feature is disabled — yields None and this error. The ImageLoader's FromExtension mode hits this path for every asset it loads.","triggerScenarios":"Loading an asset whose file extension is unknown (my_texture.avif) or whose format feature is compiled out (a .tga file in a build without bevy_image's tga feature) via ImageLoader's ImageFormatSetting::FromExtension (image_loader.rs:202-212), or calling Image::from_buffer with ImageType::Extension.","commonSituations":"Artists deliver .avif/.jxl/.psd files the pipeline cannot decode; bevy default-features = [\"png\"] builds loading .webp; asset files renamed with wrong extensions; custom asset sources producing nonstandard extensions like \"texture.png.bytes\".","solutions":["Convert the asset to a format compiled into your build (PNG is always a safe default) or rename it to a known extension that matches its actual bytes.","Enable the needed cargo feature on bevy/bevy_image for that extension (tga, tiff, webp, bmp, exr, hdr, ico, gif, pnm, ff).","Pin the format explicitly instead of relying on the extension: set ImageLoaderSettings.format = ImageFormatSetting::Format(ImageFormat::Tga) in load_with_settings or in the .meta file.","For custom extensions, load the bytes yourself and call Image::from_buffer with ImageType::Format."],"exampleFix":"// before — build has no \"tga\" feature, file is hero.tga\nlet image = server.load(\"textures/hero.tga\"); // load fails: InvalidImageExtension(\"tga\")\n\n// after — enable the feature and/or pin the format explicitly\n// Cargo.toml: bevy = { features = [\"tga\"] }\nserver.load_with_settings(\"textures/hero.tga\", |s: &mut ImageLoaderSettings| {\n    s.format = ImageFormatSetting::Format(ImageFormat::Tga);\n});","handlingStrategy":"validation","validationCode":"// validate the extension before the loader sees it\nlet ext = path.extension().and_then(|e| e.to_str()).unwrap_or(\"\");\nif ImageFormat::from_extension(ext).is_none() {\n    warn!(\"unsupported image extension {ext:?} for {path:?}\");\n    return;\n}","typeGuard":"fn extension_supported(ext: &str) -> bool {\n    ImageFormat::from_extension(ext).is_some()\n}","tryCatchPattern":"// in AssetLoadFailedEvent handling:\nif let ImageLoaderError::FileTexture(fe) = &*ev.error {\n    if let TextureError::InvalidImageExtension(ext) = &fe.error {\n        error!(\"{ext:?} files need a cargo feature or explicit format setting: {}\", fe.path);\n    }\n}","preventionTips":["Standardize the art pipeline on extensions compiled into your build (png by default).","Pin explicit formats with ImageFormatSetting::Format in .meta files for nonstandard extensions.","Add a CI check rejecting asset files whose extension is not in ImageFormat::from_extension's supported set."],"tags":["bevy","image","file-extension","feature-gate","rust"],"backgroundTag":"unsupported-file-extension","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"}