bevyengine/bevy · error · ImageLoaderError

Could not load texture file: {0}

Error message

Could not load texture file: {0}

What it means

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>.".

Source

Thrown at crates/bevy_image/src/image_loader.rs:182

            format: ImageFormatSetting::default(),
            texture_format: None,
            is_srgb: true,
            sampler: ImageSampler::Default,
            asset_usage: RenderAssetUsages::default(),
            array_layout: None,
        }
    }
}

/// An error when loading an image using [`ImageLoader`].
#[non_exhaustive]
#[derive(Debug, Error)]
pub enum ImageLoaderError {
    /// An error occurred while trying to load the image bytes.
    #[error("Failed to load image bytes: {0}")]
    Io(#[from] std::io::Error),
    /// An error occurred while trying to decode the image bytes.
    #[error("Could not load texture file: {0}")]
    FileTexture(#[from] FileTextureError),
    /// An error occurred while trying to interpret the image bytes as an array texture.
    #[error("Invalid array layout: {0}")]
    ArrayLayout(#[from] TextureReinterpretationError),
}

impl AssetLoader for ImageLoader {
    type Asset = Image;
    type Settings = ImageLoaderSettings;
    type Error = ImageLoaderError;
    async fn load(
        &self,
        reader: &mut dyn Reader,
        settings: &ImageLoaderSettings,
        load_context: &mut LoadContext<'_>,
    ) -> Result<Image, Self::Error> {
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await?;

View on GitHub (pinned to 396ca72708)

Solutions

1. Read the nested error: match ImageLoaderError::FileTexture(FileTextureError { error, path }) and act on the inner TextureError (decode, format support, or container validity).
2. Confirm the file at the printed path opens in an image viewer and its extension matches its bytes.
3. Enable missing cargo features for the format family you ship (dds, ktx2, basis-universal, tga, webp, ...).
4. Register an AssetLoadFailedEvent<Image> handler with a placeholder-texture fallback to keep the app running.

Example fix

// before — load and unwrap, crashes on any bad texture
let image = assets.get(&server.load("wall.dds")).unwrap();

// after — react to the failed asset event and inspect the nested cause
fn handle_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {
    for ev in ev.read() {
        if let ImageLoaderError::FileTexture(fe) = &*ev.error {
            error!("{} failed: {}", fe.path, fe.error); // inner TextureError + path
        }
    }
}

fn on_image_failed(mut ev: EventReader<AssetLoadFailedEvent<Image>>) {
    for ev in ev.read() {
        match &*ev.error {
            ImageLoaderError::FileTexture(fe) => {
                error!("{} failed to decode: {}", fe.path, fe.error);
                // route by inner TextureError variant: enable features / re-export / placeholder
            }
            ImageLoaderError::Io(e) => error!("io error: {e}"),
            ImageLoaderError::ArrayLayout(e) => error!("array layout: {e}"),
            _ => {} // #[non_exhaustive]
        }
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error reading image file {path}: {error}.
• Failed to load image bytes: {0}
• Invalid array layout: {0}
• Conversion into dynamic image not supported for {0:?}.
• Failed to convert into {0:?}.

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/2566febdaceef589. Report an issue: GitHub.