Skip to main content

Troubleshooting

The build cannot find OpenCascade​

Symptoms: CMake reports missing OCCT headers or libraries.

Install the pinned runtime in the same active environment before building CadFlow:

source .venv/bin/activate
python -m pip install "cadquery-ocp==7.9.3.1"
python -m pip install --no-build-isolation .

Confirm that python and pip point into the same environment. Build isolation must be disabled so CMake can discover the installed OCCT files.

ModuleNotFoundError after installation​

Check the active interpreter and installed location:

which python
python -m pip show cadflow
python -c "import cadflow; print(cadflow.__version__, cadflow.__file__)"

CadFlow supports Python 3.10 through 3.13. A different interpreter may miss dependencies or reject the package metadata.

Shapes belong to different models​

Error: all shapes must belong to this Model or a session mismatch diagnostic.

Every interacting shape must use the same native session:

with cad.Model() as model:
    body = model.box(10, 10, 2)
    tool = model.cylinder(2, 4)
    result = model.cut(body, tool)

Do not create the tool in another Model context or use a shape after its model closes.

A boolean did not change the body​

Usually the tool does not overlap the body, only touches it tangentially, or is oriented differently than expected. Inspect both bounding boxes and their distance:

print("body", body.bbox)
print("tool", tool.bbox)
print("distance", body.distance_to(tool))

Give the tool a small intentional through-overlap, perform the operation, then compare volume and solid count.

Fillet, chamfer, or shell selection fails​

Selections use deterministic zero-based indices for the current topology. Query shape.topology, call model.preflight(...), and test a small selection. A preceding feature change can alter index meaning even when the count is similar.

Use semantic tags and selectors from the compatibility layer when a reference must survive feature edits.

Validation warns about multiple solids​

Shape.validate() warns when a solid-like result does not contain exactly one solid. Decide whether the workflow expects an assembly-like result or a single fused part. For a single part, check boolean overlap and fuse the intended bodies before delivery.

STEP export is unavailable​

Native STEP writing requires the full OCCT build and may be disabled with CADFLOW_WITH_STEP=OFF. Rebuild with matching OCCT files and STEP support enabled. The compatibility STEP API may still be available, but do not silently substitute it when native parity is part of the test.

PNG rendering fails​

Rendering examples require optional packages:

python -m pip install vtk pillow matplotlib

Headless systems may also need an offscreen-capable VTK build. Geometry export does not require PNG rendering; validate STEP/STL/GLB files independently when rendering is unavailable.

Getting actionable evidence​

Include the following in a bug report:

  • CadFlow version and commit;
  • Python, CMake, compiler, OS, and architecture;
  • the OCCT version and build configuration;
  • the smallest reproducible Python script;
  • the structured OperationReport or traceback;
  • measured bounds, topology, and volume;
  • input geometry or a shareable reduced case.

Report reproducible issues in the CadFlow issue tracker.