# Troubleshooting

Common issues and solutions when using STG.

## Verilog Parsing Issues

### "No modules found in DUT file"

Make sure your Verilog file contains valid module definitions and iverilog is installed:

```bash
iverilog -t null -g2009 your_file.v
```

You can also use `stg parse` to inspect what modules are detected:

```bash
stg parse --verilog your_file.v --out modules.yaml
```

### "Multiple modules found, please specify --module"

Your file contains multiple module definitions. Specify which one to test:

```bash
stg generate --verilog file.v --module my_module ...
```

Use `stg parse` to see all available modules and their hierarchy.

### Parser fallback

STG uses a hybrid parsing approach: [sv-parser](https://github.com/dalance/sv-parser) for Rust-native parsing, with iverilog as a fallback. If sv-parser fails on your file, ensure iverilog v11+ is installed. Use `--debug` for detailed parser output.

## C++/SystemC Mode Issues

### "There are two stages to compile the testbench"

You're in stage 1 of the CC/SC workflow. First generate the template:

```bash
stg generate --verilog dut.v --type combinational --out tb.cpp --out-header golden.h --cc
```

Then implement the golden model in `golden.h` and run stage 2:

```bash
stg generate --verilog dut.v --golden golden.h --type combinational --out tb.cpp --out-exe exe --cc
```

See the [C++/SystemC Mode Guide](user_guide/cc_sc_mode.md) for the full two-stage workflow.

## Compilation Issues

### Verilator compilation errors

Try ignoring width warnings:

```bash
stg generate ... --verilator --compile-flags -Wno-WIDTH
```

### Verilator version compatibility

STG requires Verilator v5.020 or later. Older versions shipped with Linux distributions may not support required features. See the [installation guide](getting_started.md#install-verilator) for building from source.

### Module name conflicts (SV mode)

When multiple Verilog files contain modules with the same name, compilation will fail. In SV mode, use `--emplace-module` to add prefixes:

```bash
stg generate --verilog dut1.v --verilog dut2.v --golden golden.v \
  --type combinational --out tb.sv --emplace-module
```

In CC/SC mode, Verilator handles renaming automatically.

## Signal Classification Issues

### Important signals misclassified

If control signals are classified as data (or vice versa), specify them explicitly:

```bash
stg generate ... --control-signals op mode --data-signals a b
```

Use `stg identify` to preview the automatic classification:

```bash
stg identify --verilog dut.v --module my_module --type combinational --out signals.yaml
```

## FSM Coverage Issues

### "No state machines found"

The design may not contain a detectable FSM, or the coding style is not recognized by the deterministic parser. Try LLM-based extraction:

```bash
stg generate-fsm design.sv --golden golden.sv --out tb.cpp --fsm-method lm --lm-provider gemini
```

### LM method fails

- Ensure `uv` is installed: <https://docs.astral.sh/uv/>
- Check API keys in `.env` or environment variables
- Supported keys: `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`

### Missed states in coverage

- Increase `--dfs-passes` for more edge coverage
- Increase `--transition-timeout` if internal conditions (counters, timers) take many cycles
- Inspect the extracted FSM with `--state-analysis fsm.json` and verify correctness

## Runtime Issues

### Non-deterministic test results

Random test generation uses different seeds across runs. For reproducibility, consider using a fixed seed (if supported) or saving the `test_stats.json` output for comparison.

### Coverage file conflicts with MPI

In SV mode, MPI processes write to the same `coverage.dat` file, which causes conflicts. Use CC/SC mode for MPI coverage — rank-specific filenames are generated automatically.

### Path issues

Relative paths may break in different execution contexts. Use absolute paths or ensure you run STG from the correct working directory.

## Getting Help

- Run `stg --help` or `stg <command> --help` for command-line usage
- Use `--debug` for detailed diagnostic output
- Check the [CLI Reference](reference/cli.md) for all available options
- See the [examples](examples.md) for working configurations