# Text-to-CAD Troubleshooting: How to Fix Generation Errors in the earthtojake/text-to-cad Repository

> Fix Text-to-CAD generation errors in earthtojake/text-to-cad by troubleshooting skill dependencies, input formats, and viewer paths. Learn how to validate artifacts against reference schemas.

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

---

**Most Text-to-CAD failures stem from missing skill dependencies, invalid input formats, or viewer path misconfigurations that can be resolved by validating artifacts against the reference schemas in each skill's [`references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/validation.md) file.**

The earthtojake/text-to-cad repository transforms natural language prompts into manufacturable CAD models, URDF robot descriptions, and fabrication artifacts through a modular, agent-based architecture. When Text-to-CAD troubleshooting becomes necessary, understanding the strict separation between isolated skill workflows and shared utility packages is essential for diagnosing issues quickly without breaking cross-skill dependencies.

## Understanding the Repository Architecture for Debugging

The repository organizes functionality into three distinct layers. Isolating which layer produces an error is the first step in any Text-to-CAD troubleshooting workflow.

### The Skills Layer

Each skill operates as a self-contained agent workflow under `skills/<skill>/`, containing its own documentation, scripts, and validation rules. For example, the URDF skill implements its generator in [`skills/urdf/scripts/urdf/source.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/scripts/urdf/source.py) with a CLI wrapper at [`skills/urdf/scripts/urdf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/scripts/urdf/cli.py). Skills never import code from sibling skills; they only depend on shared packages, ensuring that failures remain contained within their specific domain.

### Shared Packages

The core geometry API lives in [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py), exposing functions such as `ensure_step_glb_artifact` and `validate_step_glb_artifact`. When a skill script fails during geometry generation, the error typically originates here. These packages are vendored into each skill at build time, so version mismatches between the shared library and the skill's expectations can cause subtle runtime failures.

### The Viewer Component

The browser-based preview system resides in `viewer/` and is launched via the **cad-viewer** skill. Configuration handling occurs in `viewer/src/shared/viewerConfig.mjs`, which manages port allocation and directory resolution. Viewer-related Text-to-CAD troubleshooting often involves verifying that the skill passes absolute paths to the Vite server, as relative paths cause silent loading failures in the browser.

## Common Text-to-CAD Errors and Solutions

### Dependency Installation Failures

If the `npx skills install earthtojake/text-to-cad` command fails or skills report missing modules, verify that the shared packages built correctly. Each skill vendors its dependencies at install time, so a corrupted `packages/cadpy` build will propagate to all dependent skills.

### Artifact Generation Errors

When `generation.run()` or direct API calls fail, check the validation constraints in the specific skill's [`references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/validation.md) file. For instance, the G-code skill at [`skills/gcode/scripts/gcode_tool.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/gcode/scripts/gcode_tool.py) enforces strict input format requirements before slicing. The function `ensure_step_glb_artifact` in [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) will raise validation errors if the input topology violates the skill's documented constraints.

### Viewer Rendering Issues

If the viewer launches but displays blank content, verify the directory path passed to `npx skills run cad-viewer --dir`. The viewer requires an absolute path to the `models/` directory. Check `viewer/src/shared/viewerConfig.mjs` to confirm port availability, as conflicts on the default port will prevent the server from starting without clear error messages.

## Step-by-Step Diagnostic Workflow

Follow this sequence when Text-to-CAD troubleshooting to isolate the failure layer:

1. **Verify Installation**: Run `npx skills install earthtojake/text-to-cad` and check for build errors in the shared packages output.

2. **Check Skill Documentation**: Consult `skills/<skill>/SKILL.md` for format-specific requirements. The URDF skill documentation at [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) details required input meshes and coordinate frame conventions.

3. **Validate Artifacts**: Use the validation utilities before viewer launch. The `validate_step_glb_artifact` function checks file integrity and metadata completeness that the viewer requires.

4. **Test in Isolation**: Run skill scripts directly rather than through the agent layer to bypass LLM interpretation and test core generation logic:

   ```bash
   python -m skills.urdf.scripts.urdf.cli \
       --input models/assembly.glb \
       --output models/robot.urdf
   ```

5. **Check Viewer Logs**: Launch the viewer with explicit directory flags to verify path resolution:

   ```bash
   npx skills run cad-viewer --dir "$(pwd)/models/my_model"
   ```

## Validation and Error Handling Patterns

Each skill implements error handling through its [`references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/validation.md) file, which defines required input shapes, supported file formats, and common failure modes. When validation fails, the skill returns user-readable error messages rather than stack traces. The implicit-CAD skill at `skills/implicit-cad/scripts/snapshot.mjs` demonstrates this pattern by catching geometry kernel exceptions and converting them to descriptive prompts for the LLM agent.

Unit tests located under `tests/` and executed via [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) provide additional debugging insight. For JavaScript-specific issues in the viewer or `packages/cadjs`, run the targeted test suites referenced in the CI pipeline to isolate frontend rendering bugs from backend generation errors.

## Summary

- **Text-to-CAD troubleshooting** requires identifying whether errors originate in isolated skills, shared packages, or the viewer component.
- The [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) file contains core validation functions like `ensure_step_glb_artifact` that enforce topology requirements across all skills.
- Skills maintain strict isolation under `skills/<skill>/` and rely on [`references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/validation.md) for error handling, preventing cascade failures.
- Viewer issues typically involve absolute path requirements in `viewer/src/shared/viewerConfig.mjs` or port conflicts.
- Use direct CLI invocation (e.g., `python -m skills.urdf.scripts.urdf.cli`) to bypass agent layers and test generation logic in isolation.

## Frequently Asked Questions

### Why does the viewer show a blank screen after generating a model?

The viewer requires an absolute path to the models directory, not a relative one. When launching via `npx skills run cad-viewer --dir`, use `$(pwd)/models` or the full absolute path. Also verify that `ensure_step_glb_artifact` completed successfully in the generation step, as missing GLB metadata causes silent rendering failures.

### How do I fix "Module not found" errors when running a specific skill?

These errors indicate that the shared packages failed to vendor correctly during installation. Run `npx skills install earthtojake/text-to-cad` again and check for build errors in the `packages/cadpy` output. Each skill imports from shared packages only, so reinstalling typically resolves path issues without affecting sibling skills.

### What should I check when the LLM agent produces invalid CAD geometry?

Consult the skill's [`references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/references/validation.md) file for input constraints and common failure modes. Then validate the artifact manually using `validate_step_glb_artifact` from [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) before passing it to the viewer. The validation function returns specific error messages about topology violations that help constrain the agent's next generation attempt.

### Where are the unit tests for troubleshooting specific skills?

Unit tests reside under the top-level `tests/` directory and are executed by [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh). JavaScript-specific skills like the viewer and `packages/cadjs` have separate test suites referenced in the CI pipeline. Run these directly to isolate whether failures stem from generation logic or agent prompt interpretation.