{"record":{"id":"0b7bd2e3c38acc8a","repo":"bevyengine/bevy","slug":"the-number-of-vertices-exceeds-u32-max","errorCode":null,"errorMessage":"The number of vertices exceeds u32::MAX","messagePattern":"The number of vertices exceeds u32::MAX","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/bevy_mesh/src/mesh.rs","lineNumber":1512,"sourceCode":"            .iter()\n            .map(|(k, v)| {\n                (\n                    *k,\n                    MeshAttributeData {\n                        attribute: v.attribute,\n                        values: VertexAttributeValues::new(VertexFormat::from(&v.values)),\n                    },\n                )\n            })\n            .collect();\n\n        let mut vertex_to_new_index: HashMap<VertexRef, u32> = HashMap::new();\n        let mut indices = Vec::with_capacity(self.count_vertices());\n        for i in 0..self.count_vertices() {\n            let len: u32 = vertex_to_new_index\n                .len()\n                .try_into()\n                .expect(\"The number of vertices exceeds u32::MAX\");\n            let vertex_ref = VertexRef {\n                mesh_attributes: old_attributes,\n                i,\n            };\n            let j = match vertex_to_new_index.entry(vertex_ref) {\n                hash_map::Entry::Occupied(e) => *e.get(),\n                hash_map::Entry::Vacant(e) => {\n                    e.insert(len);\n                    vertex_ref.push_to(&mut new_attributes);\n                    len\n                }\n            };\n            indices.push(j);\n        }\n        drop(vertex_to_new_index);\n\n        for v in new_attributes.values_mut() {\n            v.values.shrink_to_fit();","sourceCodeStart":1494,"sourceCodeEnd":1530,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_mesh/src/mesh.rs#L1494-L1530","documentation":"Raised by Mesh::merge_duplicate_vertices (crates/bevy_mesh/src/mesh.rs:1512) when the map of deduplicated vertices grows past u32::MAX (4,294,967,295) unique vertices. Bevy mesh index buffers store indices as u32, so the operation aborts with an expect panic instead of silently overflowing indices. In practice this guard is almost unreachable because storing that many vertices requires an enormous amount of RAM.","triggerScenarios":"Calling mesh.merge_duplicate_vertices() on a Mesh whose unique-vertex count (vertices identical across all attributes are merged into one) exceeds 2^32 - 1. Typically only possible by concatenating gigantic procedural datasets (terrain voxels, point clouds) into a single Mesh and then deduplicating.","commonSituations":"Chunked terrain or voxel engines that merge thousands of chunks into one Mesh; research/HLOD pipelines that accumulate geometry over long sessions; loading a pathological asset that expanded vertices via duplicate_vertices before deduplication.","solutions":["Split the geometry into several Meshes so each stays far below u32::MAX vertices, and deduplicate per mesh","Deduplicate vertices while building each chunk instead of after merging everything","Audit mesh.count_vertices() growth in your asset pipeline and cap or split when it approaches the limit"],"exampleFix":"// before: one giant mesh, panics when unique vertices exceed u32::MAX\nlet mut mesh = build_huge_procedural_mesh();\nmesh.merge_duplicate_vertices(); // expect(\"The number of vertices exceeds u32::MAX\")\n\n// after: keep each chunk small and dedupe per chunk\nfor mut chunk in build_huge_procedural_mesh().split_into_chunks(10_000_000) {\n    chunk.merge_duplicate_vertices()?;\n    commands.spawn(Mesh3d(meshes.add(chunk)));\n}","handlingStrategy":"validation","validationCode":"// merge_duplicate_vertices can address at most u32::MAX unique vertices\nfn can_dedupe(mesh: &Mesh) -> bool {\n    mesh.count_vertices() <= u32::MAX as usize // unique count is always <= total\n}\n\nif can_dedupe(&mesh) {\n    mesh.merge_duplicate_vertices()?;\n} else {\n    // split the mesh first\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Track count_vertices() in your asset pipeline and split meshes long before they approach 4 billion vertices","Deduplicate per chunk while generating, not after concatenating everything","Treat any mesh measured in hundreds of millions of vertices as a design smell for a single draw call"],"tags":["bevy","mesh","panic","u32-overflow","merge-duplicate-vertices","vertex-count"],"backgroundTag":"integer-overflow-panic","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}