Agent skill
freecad-automation-common-failures
Sub-skill of freecad-automation: Common Failures (+2).
Install this agent skill to your Project
npx add-skill https://github.com/vamseeachanta/workspace-hub/tree/main/.claude/skills/_archive/engineering/cad/freecad-automation/common-failures
SKILL.md
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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
vamseeachanta/workspace-hub
gsd-complete-milestone
Archive completed milestone and prepare for next version
vamseeachanta/workspace-hub
gsd-reapply-patches
Reapply local modifications after a GSD update
vamseeachanta/workspace-hub
gsd-verify-work
Validate built features through conversational UAT
vamseeachanta/workspace-hub
gsd-thread
Manage persistent context threads for cross-session work
vamseeachanta/workspace-hub
clinical-trial-protocol
Generate clinical trial protocols for medical devices or drugs through a modular, waypoint-based architecture with research-only and full protocol modes.
vamseeachanta/workspace-hub
single-cell-rna-qc
Performs quality control on single-cell RNA-seq data (.h5ad or .h5 files) using scverse best practices with MAD-based filtering and comprehensive visualizations.
Didn't find tool you were looking for?