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:

iverilog -t null -g2009 your_file.v

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

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:

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

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:

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

See the C++/SystemC Mode Guide for the full two-stage workflow.

Compilation Issues

Verilator compilation errors

Try ignoring width warnings:

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

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:

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

Use stg identify to preview the automatic classification:

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:

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 for all available options

  • See the examples for working configurations