How to Troubleshoot Common Issues with text-to-cad: A Complete Guide

Most text-to-cad failures stem from validation errors in generated artifacts, stale hardware states in external printers, or version mismatches between the cadgen runtime and individual skills.

The text-to-cad repository by earthtojake provides a collection of agent skills that generate, validate, and preview CAD and robot-description artifacts. When these automated pipelines fail, they typically emit specific error codes that point to one of three root causes: malformed file data, hardware communication issues, or dependency misalignment. Understanding where to look in the source files—such as skills/urdf/SKILL.md or skills/bambu-labs/SKILL.md—allows you to resolve issues quickly without regenerating entire pipelines.

Understanding the Three Main Failure Categories

Validation Failures in Generated Artifacts

Every skill in text-to-cad runs generated files through strict validators before reporting success. According to skills/urdf/SKILL.md, the URDF validator checks that exactly one .urdf file in the folder matches the robot name and verifies that frames, axes, visuals, and collisions are well-formed. Similarly, the SRDF skill cross-validates paired URDFs, planning groups, and end-effectors as documented in skills/srdf/SKILL.md.

For SDF files, structural errors such as missing links, unsupported rotation formats, or duplicate names trigger validation failures outlined in skills/sdf/references/validation.md. The DXF skill enforces closed cut-layer profiles and correct $INSUNITS values; deviations emit scale errors per skills/dxf/SKILL.md. Finally, the CAD Viewer surfaces loading errors—such as syntax errors in side-car *.step.js scripts or missing clip targets—in its Status tab, as noted in skills/cad-viewer/SKILL.md.

Runtime and Hardware Communication Errors

Skills interacting with external hardware, particularly Bambu Labs printers, return explicit error objects when communication fails. Common issues include stale printer state, print_error codes, and HMS (hardware-monitoring-system) failures documented in skills/bambu-labs/SKILL.md. These errors often require clearing the printer's cache and power-cycling the device before retrying the job.

Dependency Mismatch and Configuration Problems

All skills rely on the core cadgen distribution. If a skill's requirements.txt pin does not match the installed cadgen version, the CLI refuses to run and suggests an upgrade, as described in the root README.md. This prevents API mismatches that cause cryptic runtime failures.

Step-by-Step Troubleshooting Workflow

Follow this six-step process to isolate and resolve text-to-cad issues:

1. Verify the skill CLI by running cadgen <skill> --help to confirm the command is reachable and the skill is installed.

2. Run the validator manually to expose exact error codes:

cadgen <skill> validate path/to/file.ext

This shows severity levels and XML/path locations, allowing direct fixes to source files.

3. Inspect the CAD Viewer by opening cadgen viewer and loading the artifact. Check the Status and Error tabs for load-time exceptions that file-validators miss.

4. Clear hardware errors for Bambu Labs printers:

python scripts/bambu_lan_print.py clear-error --execute

This resets stale printer state so subsequent jobs can start.

5. Check version alignment between your environment and the skill:

pip list | grep cadgen

Compare the output against requirements.txt in the skill directory to prevent API mismatches.

6. Re-run the skill after fixes to confirm resolution.

Resolving Specific Error Patterns

"No paired URDF" and "Ambiguous paired URDF" Errors

This occurs when a folder contains zero or multiple .urdf files, or when the robot name does not match the SRDF's <robot name> attribute. According to skills/urdf/references/frame-semantics.md, you must rename or move files so exactly one URDF matches the SRDF declaration.

DXF Scale Errors

When $INSUNITS is missing or not set to 1 (inches) or 4 (mm), the validator emits a scale error per skills/dxf/SKILL.md. Add the appropriate header or re-export the DXF with correct units to resolve this.

Stale Printer Errors

After changing LAN or developer-mode settings, Bambu Labs printers may retain cached error flags. As documented in skills/bambu-labs/references/local-lan-protocol.md, run the clear-error script and optionally power-cycle the device before retrying.

CAD Viewer Load Errors

Syntax errors in side-car *.step.js scripts appear in the Viewer's Status tab. Fix the JavaScript or delete the side-car if unnecessary, following the patterns in skills/cad-viewer/references/viewer-features.md.

Summary

• Validation failures are the most common issue, affecting URDF, SRDF, SDF, and DXF formats with specific structural requirements.
• Hardware errors require explicit clearing via bambu_lan_print.py and potential power-cycling.
• Version mismatches between cadgen and skill requirements.txt cause CLI refusals that are resolved by aligning dependencies.
• Use the manual validator (cadgen <skill> validate) to get exact error locations before attempting fixes.
• The CAD Viewer surfaces JavaScript and loading errors not caught by file validators.

Frequently Asked Questions

Why does the text-to-cad CLI refuse to run with a dependency error?

The CLI checks that your installed cadgen version matches the pin in the skill's requirements.txt. Run pip list | grep cadgen and compare against the skill directory's requirements file, then reinstall with pip install -r skills/<name>/requirements.txt to align versions.

How do I fix "ambiguous paired URDF" when validating an SRDF file?

The SRDF validator in skills/srdf/SKILL.md requires exactly one .urdf file in the directory to match the SRDF's <robot name> attribute. Remove extra URDF files or rename them so only the target robot description remains, ensuring the name attribute matches exactly.

What causes DXF validation to fail with a scale error?

The DXF skill enforces that the $INSUNITS header variable equals 1 (inches) or 4 (millimeters). Open the DXF file and verify the header section contains the correct units value, or re-export from your CAD software with explicit unit settings as required by skills/dxf/SKILL.md.

Where do I find errors when the CAD Viewer fails to load a STEP file?

Unlike file validators, the Viewer detects runtime JavaScript errors in side-car *.step.js scripts. Launch cadgen viewer, load your file, and examine the Status tab for syntax errors or missing clip targets that prevent rendering.

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