FaceIDWrongLength in Manifold-3D MeshGL Construction

Diagnostic signature

FaceIDWrongLength

The Manifold-3D kernel emits a FaceIDWrongLength error when a supplied MeshGL object provides a faceID array whose length does not match the exact number of triangles in the mesh.

What it means

The `FaceIDWrongLength` diagnostic is an error status emitted by the Manifold-3D geometry kernel when a user supplies a malformed `MeshGL` data structure. The `MeshGL` format relies on flat arrays to transfer 3D mesh data losslessly between the kernel and external graphics systems. One of its optional reference arrays is `faceID`, which tags individual triangles with an integer identifier to trace them back to their original coplanar faces (often used for reconstructing materials after boolean operations). This diagnostic signifies that the provided `faceID` array has been populated, but its element count does not strictly equal the total number of triangles defined by the mesh.

Why it happens

Manifold-3D asserts that if the `faceID` array is utilized (i.e., it is not empty), there must be a guaranteed one-to-one mapping between the original faces and the triangulated output. The upstream validation logic explicitly checks if `mesh.faceID.size()` differs from `mesh.NumTri()` (which is derived from the length of the `triVerts` index buffer divided by 3). When manually constructing or modifying a `MeshGL` object, developers often incorrectly size this array. Common mistakes include providing one ID per complex polygon rather than one ID per triangulated subset, or leaving trailing elements after performing custom mesh slicing. When the malformed `MeshGL` is passed into a `Manifold` constructor, the internal validation routine detects this size discrepancy. To prevent downstream topological corruption, it halts processing and assigns the `FaceIDWrongLength` error status to the resulting geometry object.

Minimal reproduction

#include <manifold/manifold.h>
#include <vector>

int main() {
    manifold::MeshGL mesh;
    mesh.numProp = 3;
    
    // Create one valid triangle with 3 vertices
    mesh.vertProperties = {
        0.0f, 0.0f, 0.0f,
        1.0f, 0.0f, 0.0f,
        0.0f, 1.0f, 0.0f
    };
    mesh.triVerts = {0, 1, 2};
    
    // The mesh has exactly 1 triangle (NumTri() == 1).
    // Intentionally supply an incorrect number of face IDs (e.g., 2).
    mesh.faceID = {0, 0}; 

    // Instantiate a Manifold object from the malformed MeshGL
    manifold::Manifold m(mesh);
    
    // Verify the resulting error status
    manifold::Manifold::Error status = m.Status();
    return status == manifold::Manifold::Error::FaceIDWrongLength ? 0 : 1;
}

How to fix it

Ensure the faceID array length exactly matches the number of mesh triangles, or clear it entirely if face origin tracking is not needed.

```cpp
#include <manifold/manifold.h>
#include <vector>

int main() {
    manifold::MeshGL mesh;
    mesh.numProp = 3;
    
    mesh.vertProperties = {
        0.0f, 0.0f, 0.0f,
        1.0f, 0.0f, 0.0f,
        0.0f, 1.0f, 0.0f
    };
    mesh.triVerts = {0, 1, 2};
    
    // CORRECT: The array length strictly equals the number of triangles (1).
    mesh.faceID = {0}; 
    
    // Alternative fix if material/face tracking is unneeded:
    // mesh.faceID.clear();

    manifold::Manifold m(mesh);
    
    manifold::Manifold::Error status = m.Status();
    return status == manifold::Manifold::Error::NoError ? 0 : 1;
}

```

Step 1

• Identify the number of triangles in the MeshGL object by calling its NumTri() method, or by dividing the length of the triVerts index array by 3.

Step 2

• Review the loop or generation logic responsible for populating the faceID buffer. Ensure it pushes exactly one 32-bit unsigned integer per triangulated output face, rather than per abstract polygon.

Step 3

• If original face and material associations do not need to be preserved across subsequent boolean operations, clear the array entirely (e.g., mesh.faceID.clear() in C++ or [] in TS) to bypass the validation check entirely.

Step 4

• Pass the corrected MeshGL into the Manifold constructor and verify that the Status() query returns NoError.

Upstream references

manifold-3d manifold-3d 2.5.1 package artifact — Manifold::Error — retrieved 2026-08-11

manifold.h source declaration