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

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 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 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 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 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 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:

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:

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

Inspect the errors array to identify the root cause:

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 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.

Re-run and Commit

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

scripts/test/test.sh
scripts/test/test-python.sh

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

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:

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:

#!/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:

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, SDF XML in sdf/validation.py, URDF in urdf/__init__.py, G-code in gcode_tool.py, and DXF in 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, 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}