kalpataru-debug-rebuild

name	kalpataru-debug-rebuild
description	Diagnose Kalpataru/SolidWorks failures — sketch under-constrained, rebuild errors, missing entities, stale references after topology changes. Use whenever a tool returns ok=false or rebuild_status="failed".

Debugging Kalpataru failures

Every Kalpataru tool returns {ok: true | false, ...}. When ok is false, the response carries error, message, and often suggestion. Don't loop — read, diagnose, act once.

The error decision tree

ok=false
├── error="server_unreachable"
│   → SolidWorks not running OR add-in disabled OR wrong port.
│   → Tell the user. Don't retry.
│
├── error="no_document" / "no_part"
│   → No part is open. Call kalpataru_new_part first.
│
├── error="entity_not_found"
│   → An ID (F3, E12) is stale. Topology shifted under it.
│   → Re-query. Don't reuse the old ID.
│
├── error="under_constrained" / "underconstrained"
│   → Sketch has DOF > 0. Add dimensions/constraints.
│   → See kalpataru-sketch-workflow.
│
├── error="over_constrained" / "overconstrained"
│   → Conflicting constraints. Undo, remove one.
│
├── error="selection_required"
│   → The op needs a user click. Call kalpataru_request_selection.
│
├── error="rebuild_failed"
│   → A downstream feature can't reconcile.
│   → Read rebuild_warnings; the first warning is usually the smoking gun.
│   → Either: roll back, or edit the dependent feature.
│
└── error="invalid_parameter"
    → A value (depth, radius, etc.) was out of range or wrong type.
    → Check units, signs, magnitudes.

Rebuild failures — the most common case

When rebuild_status: "failed" appears in a feature result, SolidWorks created the new feature but couldn't rebuild a downstream one. Typical causes:

1. Topology changed: a fillet was meant to round edges E5, E7, E9, but the new feature changed which edges exist.
2. Sketch reference broken: a sketch was on face F3, but a new feature absorbed F3 into a different face.
3. Through-all cut now has nothing to cut: the body got smaller.
4. Pattern direction edge disappeared: the linear pattern's direction edge was on a face that's no longer there.

The rebuild_warnings field of the response usually names the broken feature. Read it, find the dependency, decide:

• If the change is intentional: edit the broken feature to point at new geometry.
• If the change is unintentional: kalpataru_undo and approach differently.

Under-constrained sketches

This is the #1 sketch failure. The response from kalpataru_create_sketch includes dof. If dof > 0, the sketch is under-defined.

Sketch1: dof=2, profile_closed=true

DOF=2 means two more dimensions/constraints are needed. The auto-applied constraints (horizontal/vertical, coincident at line endpoints) didn't finish the job. Common fixes:

• Anchor the sketch to the origin: add an entity at (0, 0) or use a center rectangle centered on origin.
• Add the missing dimensions: width, height, radius, distance.
• Add a symmetry constraint where applicable.

Don't extrude an under-defined sketch unless you understand the consequences — the resulting feature is fragile.

Open profiles

profile_closed: false means the boundary has gaps. The auto-coincident tries to weld endpoints within 0.001mm; if your endpoints are further apart than that, the gap stays.

Inspect the sketch entities in the response. The entities field shows [{name: "Line1", type: "line"}, ...]. Check that the end of each line matches the start of the next.

Selection-required failures

Tools that operate on a specific edge / face / plane (fillet, chamfer, revolve axis, mirror plane) need entity IDs. If you didn't provide them, the response will be selection_required.

Call:

kalpataru_request_selection(
    prompt="Pick the inside corner edges to fillet",
    select_type="edge",
    count=4,
)

The user clicks. You get back entity_ids: ["E5","E7","E9","E11"]. Pass them to the fillet.

Don't try to guess pick points to short-circuit this. SolidWorks pick-by- coordinate is unreliable across coordinate systems.

When to give up and ask the user

If you've tried the same operation twice and got the same error, stop. Tell the user what's failing and what you've tried. Don't loop. Three attempts on the same operation are almost always wasted compute.

Saving partial progress

If the part is partially built and you're stuck, save it:

kalpataru_save_part("C:\\tmp\\part-wip.SLDPRT")

So the user can pick up where you left off.