{"record":{"id":"3962aae9f0805881","repo":"bevyengine/bevy","slug":"failed-to-load-image-bytes-0","errorCode":null,"errorMessage":"Failed to load image bytes: {0}","messagePattern":"Failed to load image bytes: (.+?)","errorType":"exception","errorClass":"ImageLoaderError","httpStatus":null,"severity":"error","filePath":"crates/bevy_image/src/image_loader.rs","lineNumber":179,"sourceCode":"impl Default for ImageLoaderSettings {\n    fn default() -> Self {\n        Self {\n            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<'_>,","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_image/src/image_loader.rs#L161-L197","documentation":"ImageLoaderError::Io (image_loader.rs:179-180) wraps a std::io::Error raised by `reader.read_to_end(&mut bytes).await?` at image_loader.rs:200 — the very first step of ImageLoader::load, before any decoding. It means the asset source could not deliver the file's bytes: file missing, permission denied, path invalid, or an embedded/filesystem/custom asset source mismatch. It is Bevy's asset-pipeline-level IO error for images, converted into the loader's error type via #[from].","triggerScenarios":"server.load(\"textures/hero.png\") when the file does not exist under the assets root; permissions blocking reads in a packaged build; an Android/iOS embedded-asset source missing the file because it was added after the last packaging; watching a file being rewritten (transient read failure during hot reload).","commonSituations":"Path casing mismatches on case-sensitive filesystems (Hero.PNG vs hero.png on Linux/Android); assets folder misconfigured via AssetPlugin::file_path; files not added to the mobile bundle; network/HTTP asset sources returning IO errors.","solutions":["Verify the exact path (case-sensitive) exists under the configured asset root (default assets/).","For mobile/embedded targets, rebuild/re-copy the asset bundle so the file is included.","Handle AssetLoadFailedEvent<Image> (or check the Handle's loading state) and fall back to a placeholder texture instead of assuming success.","If it happens during hot-reload only, treat it as transient: the watcher will re-load once the write finishes."],"exampleFix":"// before — file is actually Hero.PNG on disk\nlet handle = server.load(\"textures/hero.png\"); // ImageLoaderError::Io(NotFound)\n\n// after — use the real path and react to failures\nlet handle = server.load(\"textures/Hero.PNG\");\n// system that reacts:\nfn on_load_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {\n    for ev in ev.read() {\n        error!(\"image failed: {} ({:?})\", ev.path, ev.error); // includes Io errors\n    }\n}","handlingStrategy":"try-catch","validationCode":"// verify the asset exists before requesting it (filesystem source)\nlet path = std::path::Path::new(\"assets/textures/hero.png\");\nif !path.exists() {\n    warn!(\"missing asset {path:?}\");\n    return placeholder_handle();\n}","typeGuard":null,"tryCatchPattern":"fn on_image_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>, mut commands: Commands) {\n    for ev in ev.read() {\n        if let ImageLoaderError::Io(e) = &*ev.error {\n            match e.kind() {\n                std::io::ErrorKind::NotFound => error!(\"asset {} not found\", ev.path),\n                _ => error!(\"asset io error on {}: {e}\", ev.path),\n            }\n            // spawn placeholder / queue retry after fix\n        }\n    }\n}","preventionTips":["Use exact, case-correct paths — asset paths are case-sensitive on Linux/Android even when Windows dev machines forgive.","Handle AssetLoadFailedEvent<Image> globally with a placeholder so missing art never crashes.","On mobile, rebuild the asset bundle whenever new files are added."],"tags":["bevy","asset-loading","io","file-not-found","rust"],"backgroundTag":"asset-file-io-error","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"}