bevyengine/bevy · error · ConvertAttributeError

Unknown vertex attribute {0}

Error message

Unknown vertex attribute {0}

What it means

ConvertAttributeError (unknown attribute variant): the glTF file uses a vertex attribute name that Bevy's converter does not recognize, so no target VertexAttribute format can be determined.

Source

Thrown at crates/bevy_gltf/src/vertex_attributes.rs:274

    Rgba,
    JointIndex,
    JointWeight,
    TexCoord,
}

/// Errors that can occur during the `convert_attribute` function.
#[derive(Error, Debug)]
pub enum ConvertAttributeError {
    /// The loaded format ws different than the attribute's intended format.
    /// Such as if a `Float32x3` was loaded as a `Float32x2`.
    #[error("Vertex attribute {0} has format {1:?} but expected {3:?} for target attribute {2}")]
    WrongFormat(String, VertexFormat, String, VertexFormat),
    /// Fetching values from the glTF Accessor failed
    #[error("{0} in accessor {1}")]
    AccessFailed(AccessFailed, usize),
    /// A vertex attribute name was not one of the gltf crate's well-known attributes,
    /// nor was it registered by a user as a custom attribute. Therefore it is unknown.
    #[error("Unknown vertex attribute {0}")]
    UnknownName(String),
}

/// map glTF vertex attributes into their `MeshVertexAttribute` forms, optionally
/// converting values if necessary.
pub fn convert_attribute(
    semantic: gltf::Semantic,
    accessor: gltf::Accessor,
    buffer_data: &Vec<Vec<u8>>,
    custom_vertex_attributes: &HashMap<Box<str>, MeshVertexAttribute>,
    convert_coordinates: bool,
) -> Result<(MeshVertexAttribute, Values), ConvertAttributeError> {
    if let Some((attribute, conversion, convert_coordinates)) = match &semantic {
        gltf::Semantic::Positions => Some((
            Mesh::ATTRIBUTE_POSITION,
            ConversionMode::Any,
            convert_coordinates,
        )),

View on GitHub (pinned to 396ca72708)

Solutions

1. Rename the attribute in the source asset to a Bevy-supported name (e.g. POSITION, NORMAL, TEXCOORD_n, JOINTS_n, WEIGHTS_n)
2. Register a custom attribute mapping before loading if the attribute is intentional
3. Skip unknown attributes when iterating conversion results

When it happens

Trigger: Thrown at crates/bevy_gltf/src/vertex_attributes.rs:274 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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