{"record":{"id":"2566febdaceef589","repo":"bevyengine/bevy","slug":"could-not-load-texture-file-0","errorCode":null,"errorMessage":"Could not load texture file: {0}","messagePattern":"Could not load texture file: (.+?)","errorType":"exception","errorClass":"ImageLoaderError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image_loader.rs","lineNumber":182,"sourceCode":"            format: ImageFormatSetting::default(),\n            texture_format: None,\n            is_srgb: true,\n            sampler: ImageSampler::Default,\n            asset_usage: RenderAssetUsages::default(),\n            array_layout: None,\n        }\n    }\n}\n\n/// An error when loading an image using [`ImageLoader`].\n#[non_exhaustive]\n#[derive(Debug, Error)]\npub enum ImageLoaderError {\n    /// An error occurred while trying to load the image bytes.\n    #[error(\"Failed to load image bytes: {0}\")]\n    Io(#[from] std::io::Error),\n    /// An error occurred while trying to decode the image bytes.\n    #[error(\"Could not load texture file: {0}\")]\n    FileTexture(#[from] FileTextureError),\n    /// An error occurred while trying to interpret the image bytes as an array texture.\n    #[error(\"Invalid array layout: {0}\")]\n    ArrayLayout(#[from] TextureReinterpretationError),\n}\n\nimpl AssetLoader for ImageLoader {\n    type Asset = Image;\n    type Settings = ImageLoaderSettings;\n    type Error = ImageLoaderError;\n    async fn load(\n        &self,\n        reader: &mut dyn Reader,\n        settings: &ImageLoaderSettings,\n        load_context: &mut LoadContext<'_>,\n    ) -> Result<Image, Self::Error> {\n        let mut bytes = Vec::new();\n        reader.read_to_end(&mut bytes).await?;","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_image/src/image_loader.rs#L164-L200","documentation":"ImageLoaderError::FileTexture (image_loader.rs:182-183) wraps a FileTextureError produced inside ImageLoader::load whenever image decoding/preparation fails: either image::guess_format cannot identify the bytes or the guessed format has no Bevy ImageFormat (image_loader.rs:215-224, Guess mode), or Image::from_buffer returns a TextureError (image_loader.rs:228-239) — covering every TextureError variant (bad mime/extension, decode failure, unsupported GPU format, KTX2/DDS/Basis issues). The inner FileTextureError carries both the TextureError and the asset path, so the message reads \"Could not load texture file: Error reading image file <path>: <cause>.\".","triggerScenarios":"Any failed Image asset load: corrupt PNG bytes, wrong extension mapping, compressed format unsupported by the adapter, malformed KTX2/DDS/Basis container, or an unrecognized format in ImageFormatSetting::Guess mode.","commonSituations":"Texture pipeline failures surfaced as failed Bevy asset loads; builds where bevy features (dds/ktx2/basis/tga) don't match shipped files; art hand-off introducing corrupt or renamed files.","solutions":["Read the nested error: match ImageLoaderError::FileTexture(FileTextureError { error, path }) and act on the inner TextureError (decode, format support, or container validity).","Confirm the file at the printed path opens in an image viewer and its extension matches its bytes.","Enable missing cargo features for the format family you ship (dds, ktx2, basis-universal, tga, webp, ...).","Register an AssetLoadFailedEvent<Image> handler with a placeholder-texture fallback to keep the app running."],"exampleFix":"// before — load and unwrap, crashes on any bad texture\nlet image = assets.get(&server.load(\"wall.dds\")).unwrap();\n\n// after — react to the failed asset event and inspect the nested cause\nfn handle_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {\n    for ev in ev.read() {\n        if let ImageLoaderError::FileTexture(fe) = &*ev.error {\n            error!(\"{} failed: {}\", fe.path, fe.error); // inner TextureError + path\n        }\n    }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"fn on_image_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {\n    for ev in ev.read() {\n        match &*ev.error {\n            ImageLoaderError::FileTexture(fe) => {\n                error!(\"{} failed to decode: {}\", fe.path, fe.error);\n                // route by inner TextureError variant: enable features / re-export / placeholder\n            }\n            ImageLoaderError::Io(e) => error!(\"io error: {e}\"),\n            ImageLoaderError::ArrayLayout(e) => error!(\"array layout: {e}\"),\n            _ => {} // #[non_exhaustive]\n        }\n    }\n}","preventionTips":["Log AssetLoadFailedEvent for every Image asset; the nested FileTextureError names the exact file and cause.","Run a CI job that loads the full asset set with the same feature flags as shipping builds.","Pair each texture with a placeholder fallback handle for graceful degradation."],"tags":["bevy","asset-loading","texture","rust"],"backgroundTag":"texture-load-failed","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-09T01:17:15.007Z"}