# How to Troubleshoot Common Issues with text-to-cad: A Complete Guide > Troubleshoot common text-to-cad issues like validation errors, stale hardware, or version mismatches. This guide helps you resolve common text-to-cad problems efficiently. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: how-to-guide - Published: 2026-09-13 --- **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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) or [`skills/bambu-labs/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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 --help` to confirm the command is reachable and the skill is installed. 2. **Run the validator manually** to expose exact error codes: ```bash cadgen 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: ```bash 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: ```bash pip list | grep cadgen ``` Compare the output against [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/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 `` attribute. According to [`skills/urdf/references/frame-semantics.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/bambu_lan_print.py) and potential power-cycling. - **Version mismatches** between `cadgen` and skill [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) cause CLI refusals that are resolved by aligning dependencies. - Use the manual validator (`cadgen 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`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt). Run `pip list | grep cadgen` and compare against the skill directory's requirements file, then reinstall with `pip install -r skills//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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/srdf/SKILL.md) requires exactly one `.urdf` file in the directory to match the SRDF's `` 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`](https://github.com/earthtojake/text-to-cad/blob/main/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.