freecad-automation-common-failures

name	freecad-automation-common-failures
description	Sub-skill of freecad-automation: Common Failures (+2).
version	2.0.0
category	engineering
type	reference
scripts_exempt	true

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): freecadcmd includes FreeCADGui as a no-op stub — import FreeCADGui succeeds but GUI operations are non-functional. Safe to use in scripts that conditionally check for GUI availability.