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

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 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 with a CLI wrapper at 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, 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 file. For instance, the G-code skill at 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 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 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:

   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:

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

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