# How to Debug text-to-CAD: A Complete Troubleshooting Guide

> Debug text-to-CAD effectively with this troubleshooting guide. Use verbose flags, trace execution, and inspect CadModel objects to find and fix generation errors in your workflow.

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

---

**Use the `--verbose` flag to activate `CliLogger` timing contexts, trace execution through the generation pipeline in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py), and inspect intermediate `CadModel` objects via interactive Python sessions to isolate failures in the CAD generation workflow.**

The `earthtojake/text-to-cad` repository transforms plain-language prompts and Python scripts into manufacturable STEP, GLB, and STL files. When the pipeline fails silently or produces malformed geometry, systematic debugging requires tracing data flow through the CLI entry points, logging infrastructure, and core generation engine.

## Understand the text-to-CAD Architecture

Effective debugging starts with knowing which layer handles your specific failure. The repository organizes functionality into distinct modules that pass data from user input to final artifact.

### CLI Entry Points

The [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py) file parses arguments like `--verbose` and `--output`, then dispatches to the generation pipeline. This is the first place to verify that your command-line flags reach the underlying functions. When you append `--verbose`, the CLI instantiates `CliLogger(name="scripts/step", verbose=True)` and propagates it downstream.

### Generation Engine

The heart of the system lives in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py). This module walks target Python files, constructs a `CadModel` instance, and coordinates mesh creation and export. Failures here manifest as missing output files or geometry exceptions. Place breakpoints inside the `generate_from_files` function to inspect the model before it reaches the exporter.

### Logging Infrastructure

Uniform diagnostic output comes from [`packages/cadpy/src/cadpy/cli_logging.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/cli_logging.py). The `CliLogger` class provides `info()`, `debug()`, and `timing()` methods that wrap code blocks in measured contexts. When `--verbose` is active, these calls print timestamped stage durations to stderr, revealing bottlenecks in parsing, meshing, or file I/O.

## Step-by-Step Debugging Workflow

Trace failures systematically by moving from surface-level CLI diagnostics to deep code inspection.

1. **Enable verbose output at the command line.**  
   Run your generation command with the `--verbose` flag to surface timing data for each major stage.  
   ```bash
   text-to-cad cad parts/sample.py --output models/sample.step --verbose
   ```  
   This activates `CliLogger.timing` contexts around parsing, mesh creation, and export operations, printing durations like `[scripts/step] mesh creation completed in 1.2s`.

2. **Inspect intermediate objects in a REPL.**  
   Import the generation module directly to examine the `CadModel` before it hits the disk.  
   ```python
   from cadpy import generate_from_files
   model = generate_from_files(["parts/sample.py"], verbose=True)
   model.inspect()  # Prints vertices, faces, and bounding box

   ```

3. **Validate STEP metadata independently.**  
   If the output file is corrupt, run the validation routine directly against the artifact helper.  
   ```bash
   python -m cadpy.step_artifact --validate models/sample.step
   ```  
   This uses [`step_metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_metadata.py) to report missing entities or schema violations without running the full generation pipeline.

4. **Use the local CAD viewer for visual feedback.**  
   Launch the viewer to catch rendering errors that indicate underlying geometry issues.  
   ```bash
   npx skills install earthtojake/text-to-cad
   skills run cad-viewer --dir $(pwd)/models
   ```  
   The viewer logs `CliLogger` messages to its console, correlating UI failures with CLI pipeline stages.

5. **Run targeted unit tests.**  
   The test suite in [`tests/python/skills/cad/step/test_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/tests/python/skills/cad/step/test_cli.py) exercises CLI flags and generation paths with mocked arguments.  
   ```bash
   ./scripts/test/test.sh -k test_cli
   ```  
   Failures here pinpoint exact functions that misbehave under specific input conditions.

6. **Inject temporary logging for custom code.**  
   When `--verbose` is insufficient, instantiate a logger directly in your script.  
   ```python
   from cadpy.cli_logging import CliLogger
   logger = CliLogger("my-debug", verbose=True)
   with logger.timed("custom-step"):
       # Your debugging code here

       pass
   ```

7. **Verify artifacts in the `models/` directory.**  
   Confirm that expected files (STEP, STL, GLB) exist with non-zero size. Missing files usually indicate an early exit in [`generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/generation.py) before the export stage completes.

## Code Examples for Common Debugging Scenarios

### Debugging Step Generation with Timing Output

Generate a part while capturing per-stage performance metrics to identify slow operations.

```bash
text-to-cad cad parts/sample.py \
    --output models/sample.step \
    --verbose

```

The output reveals precise timing for each pipeline phase:

```

[scripts/step] parsing started
[scripts/step] parsing completed in 45ms
[scripts/step] mesh creation started
[scripts/step] mesh creation completed in 1.2s

```

### Interactive Model Inspection

When geometry looks wrong, examine the mesh attributes before exporting.

```python
from cadpy import generate_from_files

model = generate_from_files(["parts/sample.py"], verbose=True)
model.inspect()

# Output: Vertices: 1243, Faces: 2360, Bounds: (0,0,0)-(100,50,20) mm

# Export manually after verification

model.mesh.to_stl("models/sample.stl")

```

### Validating GLB Exports in the Viewer

Debug WebGL-specific export issues by loading the generated file in the local viewer.

```bash

# Generate the GLB first

text-to-cad cad parts/sample.py --output models/sample.glb --verbose

# Launch viewer pointing at the models folder

npx skills run cad-viewer --dir $(pwd)/models

```

Open the URL printed by the viewer (typically `http://127.0.0.1:4178`). If the model fails to load, check the viewer console for `CliLogger` error messages that mirror the CLI output.

## Summary

- **Start with `--verbose`** to activate `CliLogger` timing contexts in [`packages/cadpy/src/cadpy/cli_logging.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/cli_logging.py) and surface stage-level diagnostics.
- **Trace the data flow** from [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py) through [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) to isolate where the pipeline exits early.
- **Inspect interactively** using `generate_from_files()` and `model.inspect()` to verify geometry before it reaches the exporter.
- **Validate artifacts** with `python -m cadpy.step_artifact --validate` for STEP-specific schema compliance.
- **Leverage the viewer** at `skills/cad-viewer/scripts/viewer/` to catch rendering errors and correlate them with generation logs.

## Frequently Asked Questions

### How do I enable verbose logging in text-to-CAD?

Append the `--verbose` flag to any `text-to-cad cad` command. This instantiates `CliLogger` with verbose mode enabled in [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py), causing the generation pipeline in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) to print timestamped stage durations and debug messages to stderr.

### Where should I place breakpoints when debugging generation failures?

Set breakpoints inside `generate_from_files()` in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py). This function orchestrates the entire pipeline, making it ideal for inspecting the `CadModel` object after mesh creation but before export. You can also break inside [`cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/cli.py) to verify that command-line arguments parse correctly before reaching the engine.

### How can I inspect intermediate CAD models during execution?

Import `generate_from_files` from the `cadpy` package in an interactive Python session. Call the function with your input files and `verbose=True`, then invoke `.inspect()` on the returned model object to print vertex counts, face statistics, and bounding box dimensions without writing to disk.

### What is the best way to validate exported STEP files?

Use the standalone validation module: `python -m cadpy.step_artifact --validate path/to/file.step`. This runs the validation logic from [`packages/cadpy/src/cadpy/step_artifact.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_artifact.py) against STEP metadata requirements and reports missing entities or schema violations directly, bypassing the full generation pipeline.