vamseeachanta Common Failures (+2)
Common Failures
| Error | Cause | Fix |
|---|---|---|
ModuleNotFoundError: No module named 'FreeCAD' |
FreeCAD not in Python path | Add to path: sys.path.append('/usr/lib/freecad-daily/lib') or use freecadcmd |
FreeCAD.openDocument(): file not found |
Wrong path or .FCStd corrupted | Check path; try opening in GUI first |
Part.BRepBuilderAPI: shape is not valid |
Invalid geometry (self-intersection) | Run shape.fix(0.1, 0.1, 0.1) or simplify geometry |
Mesh export produces 0-byte STL |
No mesh-compatible objects | Ensure objects have Shape; use Part before Mesh export |
Boolean operation failed |
Overlapping/touching geometry | Add small offset (0.01mm) between bodies; check geometry validity |
Recompute failed |
Sketches over-/under-constrained | Check obj.Shape.isValid() and sketch DOF count |
ImportError: No module named 'FreeCADGui' |
Running headless without GUI module (FreeCAD < 0.21) | FreeCAD ≥ 0.21: freecadcmd includes FreeCADGui (no-op window); safe to import. FreeCAD < 0.21: use freecadcmd and avoid Gui-dependent operations |
Diagnostic Function
import FreeCAD
def diagnose_freecad_model(doc_path):
"""Diagnose common FreeCAD model issues."""
diag = {"issues": [], "warnings": [], "info": []}
try:
doc = FreeCAD.openDocument(doc_path)
except Exception as e:
*See sub-skills for full details.*
## Headless Execution Troubleshooting
```bash
# FreeCAD headless (no GUI)
freecadcmd script.py
# If freecadcmd not found, use full path
/usr/bin/freecadcmd script.py
# Alternative: use FreeCAD with -c flag
freecad -c "exec(open('script.py').read())"
# Check FreeCAD Python path
python3 -c "import sys; sys.path.append('/usr/lib/freecad-daily/lib'); import FreeCAD; print(FreeCAD.Version())"
Note (FreeCAD ≥ 0.21):
freecadcmdincludesFreeCADGuias a no-op stub —import FreeCADGuisucceeds but GUI operations are non-functional. Safe to use in scripts that conditionally check for GUI availability.