bevyengine/bevy · error · MeshTrianglesError

Face index data references vertices that do not exist

Error message

Face index data references vertices that do not exist

What it means

MeshTrianglesError::BadIndices reports that face index data references vertices that do not exist: an index in the Indices buffer is greater than or equal to the vertex count. Triangle-producing mesh APIs use this variant when they validate the index buffer against the vertex attribute buffers.

Source

Thrown at crates/bevy_mesh/src/index.rs:74

    /// This error occurs when you try to invert the winding for a mesh with
    /// * [`PrimitiveTopology::TriangleList`](super::PrimitiveTopology::TriangleList), but the indices are not in chunks of 3.
    /// * [`PrimitiveTopology::LineList`](super::PrimitiveTopology::LineList), but the indices are not in chunks of 2.
    #[error("Indices weren't in chunks according to topology")]
    AbruptIndicesEnd,
    #[error("Mesh access error: {0}")]
    MeshAccessError(#[from] MeshAccessError),
}

/// An error that occurred while trying to extract a collection of triangles from a [`Mesh`](super::Mesh).
#[derive(Debug, Error)]
pub enum MeshTrianglesError {
    #[error("Source mesh does not have primitive topology TriangleList or TriangleStrip")]
    WrongTopology,

    #[error("Source mesh position data is not Float32x3")]
    PositionsFormat,

    #[error("Face index data references vertices that do not exist")]
    BadIndices,
    #[error("mesh access error: {0}")]
    MeshAccessError(#[from] MeshAccessError),
}

/// An array of indices into the [`VertexAttributeValues`](super::VertexAttributeValues) for a mesh.
///
/// It describes the order in which the vertex attributes should be joined into faces.
#[derive(Debug, Clone, Reflect, PartialEq)]
#[reflect(Clone)]
#[cfg_attr(feature = "serialize", derive(Serialize, Deserialize))]
pub enum Indices {
    U16(Vec<u16>),
    U32(Vec<u32>),
}

impl Indices {
    /// Returns an iterator over the indices.

View on GitHub (pinned to 396ca72708)

Solutions

1. Validate indices against mesh.count_vertices() before calling triangle-extraction APIs: every index must be < vertex count
2. Rebuild or remap the index buffer whenever vertex data is edited
3. Filter out or clamp out-of-range indices when repairing imported data

Example fix

// before
let tris: Vec<Triangle3d> = mesh.triangles()?.collect(); // Err(BadIndices) on stale indices

// after (validate before extracting)
let vertex_count = mesh.count_vertices();
let valid = mesh.indices().is_none_or(|i| match i {
    Indices::U16(v) => v.iter().all(|&i| (i as usize) < vertex_count),
    Indices::U32(v) => v.iter().all(|&i| (i as usize) < vertex_count),
});
if valid {
    let tris: Vec<Triangle3d> = mesh.triangles()?.collect();
}

fn indices_in_bounds(mesh: &Mesh) -> bool {
    let vertex_count = mesh.count_vertices();
    match mesh.indices() {
        Some(Indices::U16(v)) => v.iter().all(|&i| (i as usize) < vertex_count),
        Some(Indices::U32(v)) => v.iter().all(|&i| (i as usize) < vertex_count),
        None => true,
    }
}

match mesh.triangles() {
    Ok(iter) => { /* use triangles */ }
    Err(MeshTrianglesError::BadIndices) => { /* rebuild the index buffer against count_vertices(), then retry */ }
    Err(other) => { /* topology / format / access errors */ }
}

When it happens

Trigger: A mesh whose index buffer contains values >= mesh.count_vertices(); stale indices left in place after the position attribute was truncated or replaced; concatenated meshes where indices were not offset.

Common situations: Editing vertex buffers without rebuilding indices; merging meshes while forgetting index offsets; hand-authored index lists referencing deleted vertices; corrupted imported assets.

Related errors

• Indices weren't in chunks according to topology
• Source mesh does not have primitive topology TriangleList or
• Source mesh position data is not Float32x3
• mesh access error: {0}
• cannot convert VertexAttributeValues::{variant} to {into}

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