# How to Repair Failed CAD Validation: A Complete Loop Procedure for the text-to-CAD Pipeline

> Learn how to repair failed CAD validation in the text-to-CAD pipeline. This guide details a systematic repair loop to fix issues like missing GLB exports and schema mismatches for successful validation.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-04

---

**When CAD validation fails in the text-to-CAD pipeline, execute a systematic repair loop that captures the ValidationResult JSON, maps error reasons to generator source code, patches the specific failure—such as missing GLB exports or schema mismatches—and re-runs with `--strict` until all topology, XML, and format checks pass.**

The earthtojake/text-to-cad repository generates complex CAD artifacts that must pass rigorous validation checks before reaching downstream tools like viewers, slicers, and simulators. When validation fails—whether due to missing GLB topology attributes, schema version mismatches, or unresolved mesh URIs—a structured repair loop procedure is required to maintain pipeline integrity. This guide walks through the exact validation architecture, common failure modes, and the step-by-step repair workflow used to fix failed CAD validation errors.

## Understanding the Validation Architecture

The repository implements domain-specific validators that return a **`ValidationResult`** object containing `errors`, `warnings`, and `infos`. The helper **`raise_for_validation_errors()`** aborts execution if any errors (or warnings when `--strict` is set) are present.

### STEP and GLB Topology Validation

**STEP topology validation** occurs in [`packages/cadpy/src/cadpy/step_targets.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_targets.py) via the **`validate_step_topology()`** function. This validator checks for:

- Presence of generated GLB artifacts
- Readable `STEP_topology` views (`indexView`, `edgeView`, `selectorView`)
- Schema version matching `STEP_TOPOLOGY_SCHEMA_VERSION`
- Required mesh attributes: `STEP_EDGE_BARYCENTRIC_ATTRIBUTE` and `STEP_EDGE_CLASS_ATTRIBUTE`
- Non-zero edge class values on generated surface edges

### SDF XML and URDF Validation

**SDF validation** runs through [`skills/sdf/scripts/sdf/validation.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/sdf/scripts/sdf/validation.py) using **`validate_sdf_xml()`** and **`raise_for_validation_errors()`**. It verifies valid XML schema, correct mesh URI schemes, resolved scoped references, and disallows warnings in strict mode.

**URDF validation** appears in [`skills/urdf/scripts/urdf/__init__.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/scripts/urdf/__init__.py) via **`validate_urdf()`**, checking well-formed XML, correct joint/limit definitions, and resolving mesh URIs to bundled assets.

### G-code and DXF Checks

**G-code validation** resides in [`skills/gcode/scripts/gcode_tool.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/gcode/scripts/gcode_tool.py) within **`_raise_for_failed_generation()`**, validating extrusion bounds against printer limits, flagging unknown commands, and handling relative/absolute positioning modes.

**DXF validation** uses [`skills/dxf/scripts/dxf/validation.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/dxf/scripts/dxf/validation.py) via **`validate_dxf()`** to verify correct layer types and numeric tolerances.

## Common CAD Validation Failure Modes

Understanding specific error patterns accelerates the repair loop. The most frequent failures encountered in the text-to-CAD pipeline include:

- **Missing GLB artifact**: The STEP generator produced a STEP file but skipped the GLB export step. Error: *"STEP topology validation requires the generated GLB artifact, but it is missing"*.
- **Schema version mismatch**: The GLB's `STEP_topology` view reports a `schemaVersion` different from the expected `STEP_TOPOLOGY_SCHEMA_VERSION`.
- **Absent mesh attributes**: Edge primitives lack barycentric or class attributes. Error: *"STEP topology validation requires STEP_EDGE_BARYCENTRIC_ATTRIBUTE and STEP_EDGE_CLASS_ATTRIBUTE on STEP mesh primitives"*.
- **Zero-length edge class**: Generated surface edges have a class value of 0, breaking edge-class selection logic.
- **Unresolved Mesh URI**: SDF/URDF files reference meshes using schemes (`myproto://`) not in the validator's whitelist (`file`, `http`, `data`).
- **Relative positioning warnings**: G-code runs in relative mode, causing XYZ bounds validation to skip while emitting warnings.
- **Unknown G-code commands**: The slicer CLI emits commands unrecognized by the validator.

## The Repair Loop Procedure

The repository follows a **generate → validate → iterate** workflow. Use this exact procedure to repair failed CAD validation errors.

### Run with Strict Mode Enabled

Execute the skill with the **`--strict`** flag to treat warnings as failures, ensuring comprehensive validation:

```bash
npx skills run cad --prompt "a 100 mm cube with a 10 mm hole" --strict

```

### Capture and Parse ValidationResult

The CLI prints a JSON-encoded `ValidationResult` on failure. Capture it for analysis:

```bash
npx skills run cad --prompt "a 100 mm cube" --strict 2>validation.json

```

Inspect the `errors` array to identify the root cause:

```python
import json
with open('validation.json') as f:
    result = json.load(f)
print(result['errors'])

```

Each error contains a `reason` field mapping directly to source-code checks listed above.

### Locate and Patch Generator Code

Trace the error reason to the validator file, then back to the generator routine:

1. **Missing GLB**: Ensure the generator calls `export_glb()` before validation.
2. **Schema mismatch**: Update `STEP_TOPOLOGY_SCHEMA_VERSION` in [`step_targets.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_targets.py) or regenerate the GLB with the correct version.
3. **Missing attributes**: Add `mesh.add_attribute(...)` calls for `STEP_EDGE_BARYCENTRIC_ATTRIBUTE` and `STEP_EDGE_CLASS_ATTRIBUTE` before saving.
4. **Invalid URIs**: Place mesh files under the skill's `assets/` folder and use whitelisted schemes (`file://`, `http://`, `data://`).

Apply changes in the symlink-resolved source path as documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).

### Re-run and Commit

Execute the same command again. If validation passes, run the test suite to prevent regressions:

```bash
scripts/test/test.sh
scripts/test/test-python.sh

```

Add a regression test in `tests/python/skills/<skill>/` to guard against future failures:

```python
import unittest
from cadpy.io import load_glb
from cadpy.step_targets import validate_step_topology

class TestStepTopology(unittest.TestCase):
    def test_simple_cube_topology(self):
        glb = load_glb("tests/fixtures/simple_cube.glb")
        result = validate_step_topology(glb)
        self.assertFalse(result.errors, msg=result.errors)

```

## Code Examples for Validation Repair

### Direct Python Validation

Validate STEP topology programmatically using the same functions called by the CLI:

```python
from cadpy.step_targets import validate_step_topology
from cadpy.io import load_glb
from sdf.validation import raise_for_validation_errors

# Load generated artifact

glb = load_glb("output/my_model.glb")

# Execute validation

result = validate_step_topology(glb)

# Strict mode exception handling

raise_for_validation_errors(result, strict=True)

```

### CLI Repair Automation

Automate the repair loop with a bash script that captures and inspects validation output:

```bash
#!/usr/bin/env bash
set -euo pipefail

PROMPT="a 120 mm shaft with a keyway"
OUT_DIR="generated"

# Generate with strict validation

npx skills run cad --prompt "$PROMPT" --output "$OUT_DIR" --strict 2>validation.json || true

# Check for errors

if jq -e '.errors|length>0' validation.json; then
  echo "Validation failed:"
  jq '.errors[].reason' validation.json
  # Edit generator code, then repeat

else
  echo "Validation succeeded!"
fi

```

### Regression Testing

Create targeted tests to ensure specific validation failures do not recur:

```python
import unittest
from cadpy.io import load_glb
from cadpy.step_targets import validate_step_topology

class TestStepTopology(unittest.TestCase):
    def test_simple_cube_topology(self):
        glb = load_glb("tests/fixtures/simple_cube.glb")
        result = validate_step_topology(glb)
        self.assertFalse(result.errors, msg=result.errors)

```

## Summary

- **Validation spans multiple domains**: STEP/GLB topology in [`step_targets.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_targets.py), SDF XML in [`sdf/validation.py`](https://github.com/earthtojake/text-to-cad/blob/main/sdf/validation.py), URDF in [`urdf/__init__.py`](https://github.com/earthtojake/text-to-cad/blob/main/urdf/__init__.py), G-code in [`gcode_tool.py`](https://github.com/earthtojake/text-to-cad/blob/main/gcode_tool.py), and DXF in [`dxf/validation.py`](https://github.com/earthtojake/text-to-cad/blob/main/dxf/validation.py).
- **Use `--strict` mode** to surface all warnings as errors during the repair loop.
- **Parse `ValidationResult` JSON** to map error reasons directly to specific generator code requiring patches.
- **Common fixes include**: adding `export_glb()` calls, updating `STEP_TOPOLOGY_SCHEMA_VERSION`, populating mesh attributes with `add_attribute()`, and ensuring mesh URIs use whitelisted schemes.
- **Always run the test suite** after validation passes and add regression tests to prevent future failures.

## Frequently Asked Questions

### What causes the "STEP topology validation requires the generated GLB artifact" error?

This error occurs when the CAD skill generates a STEP file but fails to execute the GLB export step before validation triggers. According to the source code in [`packages/cadpy/src/cadpy/step_targets.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_targets.py), the `validate_step_topology()` function requires the GLB artifact to inspect `STEP_topology` views. To repair this, ensure the generator code calls `export_glb()` prior to the validation checkpoint.

### How do I fix schema version mismatches in STEP topology validation?

The validator checks that the GLB's `STEP_topology` view contains a `schemaVersion` matching the constant `STEP_TOPOLOGY_SCHEMA_VERSION` defined in [`step_targets.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_targets.py). When these versions diverge, validation fails. Repair this by either bumping the constant in the validation file to match your generated output, or regenerating the GLB using the exact schema version expected by the current validator.

### Why does my SDF file fail validation with unresolved mesh URI errors?

The SDF validator in [`skills/sdf/scripts/sdf/validation.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/sdf/scripts/sdf/validation.py) maintains a whitelist of resolvable URI schemes including `file`, `http`, and `data`. If your robot description references meshes using custom schemes like `myproto://`, validation fails. To repair this, place mesh assets under the skill's `assets/` directory and reference them using relative `file://` paths or other whitelisted schemes that the bundled validation can resolve.