bevyengine/bevy · error · GltfError

You may need to add the feature for the file format: {0}

Error message

You may need to add the feature for the file format: {0}

What it means

GltfError::ImageError wraps TextureError from Image::from_buffer when decoding embedded texture bytes (mod.rs:1228-1235 and 1250-1257). The message 'You may need to add the feature for the file format' is literal advice: Bevy gates every image codec behind a cargo feature on bevy_image (png, jpeg, webp, hdr, basis-universal, ktx2, tga, dds, ...). A perfectly valid JPEG/KTX2/etc. texture fails here when its feature is not enabled; corrupt image bytes surface through the same variant.

Source

Thrown at crates/bevy_gltf/src/loader/mod.rs:112

    Gltf(#[from] gltf::Error),
    /// Binary blob is missing.
    #[error("binary blob is missing")]
    MissingBlob,
    /// Decoding the base64 mesh data failed.
    #[error("failed to decode base64 mesh data")]
    Base64Decode(#[from] base64::DecodeError),
    /// Unsupported buffer format.
    #[error("unsupported buffer format")]
    BufferFormatUnsupported,
    /// The buffer URI was unable to be resolved with respect to the asset path.
    #[error("invalid buffer uri: {0}. asset path error={1}")]
    InvalidBufferUri(String, ParseAssetPathError),
    /// Invalid image mime type.
    #[error("invalid image mime type: {0}")]
    #[from(ignore)]
    InvalidImageMimeType(String),
    /// Error when loading a texture. Might be due to a disabled image file format feature.
    #[error("You may need to add the feature for the file format: {0}")]
    ImageError(#[from] TextureError),
    /// The image URI was unable to be resolved with respect to the asset path.
    #[error("invalid image uri: {0}. asset path error={1}")]
    InvalidImageUri(String, ParseAssetPathError),
    /// Failed to read bytes from an asset path.
    #[error("failed to read bytes from an asset path: {0}")]
    ReadAssetBytesError(#[from] ReadAssetBytesError),
    /// Failed to load asset from an asset path.
    #[error("failed to load asset from an asset path: {0}")]
    AssetLoadError(#[from] AssetLoadError),
    /// Missing sampler for an animation.
    #[error("Missing sampler for animation {0}")]
    #[from(ignore)]
    MissingAnimationSampler(usize),
    /// Failed to generate tangents.
    #[error("failed to generate tangents: {0}")]
    GenerateTangentsError(#[from] bevy_mesh::GenerateTangentsError),
    /// Failed to generate morph targets.

View on GitHub (pinned to 396ca72708)

Solutions

1. Enable the matching cargo features on bevy: features = ["jpeg", "webp", "ktx2", "basis-universal", "hdr"] as needed.
2. Read the {0} payload — it names the exact format string that failed, which maps 1:1 to the feature name.
3. Alternatively re-encode the model's textures to PNG.
4. Distinguish a disabled feature (UnsupportedImageFormat) from corrupt bytes (e.g. TextureError::ImageErrorDecoder) in your error handler.

Example fix

# Cargo.toml (before)
bevy = "0.16"
# (after) model embeds jpg + ktx2/basis textures
bevy = { version = "0.16", features = ["jpeg", "ktx2", "basis-universal"] }

// features are compile-time; validate your project declares what your assets use
// (jpeg -> "jpeg", ktx2/basis -> "ktx2" + "basis-universal", radiance -> "hdr")
fn formats_enabled() -> Vec<&'static str> { /* read from cfg!(feature = ...) of your app crate */ vec![] }

match err {
    GltfError::ImageError(tex_err) => {
        warn!("texture failed: {tex_err}; falling back to gray texture");
        placeholder_material()
    }
    other => return Err(other.into()),
}

When it happens

Trigger: Default bevy enables only a small set of image features (png among them); a glTF embedding or referencing jpg/webp/ktx2/basis/hdr textures fails TextureError::UnsupportedImageFormat, which #[from] converts into this error at load time.

Common situations: First run of a textured model downloaded from Sketchfab/Quixel (often jpg + ktx2), PBR packs with HDR environments, or switching a project from embedded PNGs to compressed basis textures without updating Cargo features.

Related errors

• invalid image mime type: {0}
• invalid image uri: {0}. asset path error={1}
• Field name should exist
• Field name should be a valid tuple index
• unsupported primitive mode

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