Troubleshooting

RyuSim error messages, their causes and fixes.

Each entry starts with the message as RyuSim or cocotb prints it, then gives the cause and the fix. Most entries include commands that reproduce the message. Entries that need a broken toolchain to reproduce show the output instead.

Messages

Toolchain

clang++ not found on PATH
zlib development library (libz.so) not found
ninja is not on PATH
cmake: not found
genhtml command not found

Compile

File does not exist
Compilation produced 1 error(s)
Top module '…' not found in design
unsupported construct
typed sim build failed
IR2-DROP

Simulation

combinational cycle did not converge
The simulation does not exit
An old executable is still in obj_dir
Could not load VPI library

cocotb

cocotbext-ryusim-config: No such file or directory
find_libpython was not able to find a libpython
Couldn't find makefile for simulator: "ryusim"
Unable to locate command >ryusim<
Simulator 'ryusim' is not in supported list
ERROR: ryusim executable not found!
hdl_toplevel argument is required
cocotbext-ryusim requires cocotb>=2.1,<2.2
No GPI_USERS specified
PYGPI_PYTHON_BIN variable not set

Toolchain

ryusim compile generates C++ and builds it on your machine. The build needs Clang, the zlib development files, and ninja or CMake. The Getting Started page lists the packages for each distribution. The output in this section is from ryusim -q compile on a machine missing the tool named.

`clang++ not found on PATH`

Warning: build.ninja not generated (clang++ not found on PATH (clang++-19, clang++-18, clang++) — RyuSim generated code requires Clang); the CMake driver will build this design
Warning: build driver: cmake (no build.ninja in obj_dir (the ninja build file was not generated))
Error: CMake configuration failed
CMake Error at CMakeLists.txt:5 (message):
  clang++ not found; RyuSim generated code requires Clang


-- Configuring incomplete, errors occurred!

Cause. RyuSim looks for clang++-19, clang++-18 and clang++ on PATH, in that order, and found none of them. It then hands the build to CMake, and the generated CMakeLists.txt stops. GCC cannot build the generated code. Designs with DPI .c sources also need the matching clang.

Fix. Install Clang (the packages are on Getting Started) and make sure one of those three names is on PATH. Check with:

command -v clang++-19 clang++-18 clang++

`zlib development library (libz.so) not found`

Warning: build.ninja not generated (zlib development library (libz.so) not found — the RyuSim runtime's FST writer links it; on Debian/Ubuntu install zlib1g-dev, on Fedora/Rocky zlib-devel); the CMake driver will build this design

As with a missing Clang, the build then falls to CMake. CMake stops with Could NOT find ZLIB, and RyuSim prints Error: CMake configuration failed.

Cause. Every generated simulation links zlib, because the runtime's FST waveform writer uses it. Linking needs libz.so. Without the development package a system has only libz.so.1, the runtime library.

Fix. Install zlib1g-dev on Debian and Ubuntu, or zlib-devel on Fedora, Rocky and RHEL:

sudo apt install zlib1g-dev

`ninja is not on PATH`

Warning: build driver: cmake (ninja is not on PATH; the generated build.ninja cannot be driven — install ninja-build for the configure-free build)

Cause. RyuSim writes a build.ninja and a CMakeLists.txt for every design. It builds with ninja when ninja is on PATH, and with CMake when it is not.

Fix. None is needed: the build continues with CMake and the warning names the driver that ran. The driver is also recorded as "build_driver" in obj_dir/ryusim-route.json. To build with ninja, install the ninja-build package.

`cmake: not found`

Warning: build driver: cmake (ninja is not on PATH; the generated build.ninja cannot be driven — install ninja-build for the configure-free build)
Error: CMake configuration failed
sh: 1: cmake: not found

Cause. Neither ninja nor CMake is on PATH, so nothing can build the generated C++.

Fix. Install ninja (ninja-build) or CMake. One of the two is enough.

`genhtml command not found`

RyuSim - Generating HTML coverage report
  Input: coverage.info
  Output: html
Error: genhtml command not found.
  Please install lcov package (apt install lcov or equivalent)

Cause. ryusim coverage html renders the report with genhtml, which is part of lcov.

Fix. Install the lcov package. Collecting and merging coverage does not need it. See Coverage.

Compile

The examples in this section use ryusim -q, which prints only warnings and errors.

`File does not exist`

ryusim -q compile nosuch.sv --top top 2>&1 || true

sources: File does not exist: nosuch.sv
Run with --help for more information.

Cause. A source file on the command line does not exist. Paths are relative to the directory you run ryusim in. A missing -f file list gives --filelist: File does not exist: ….

Fix. Correct the path, or run from the directory the paths are relative to. Nothing is generated; the exit status is 105.

`Compilation produced 1 error(s)`

module top;
  logic a
endmodule

ryusim -q compile syntax.sv --top top 2>&1 || true

syntax.sv:2:10: error: expected ';'
  logic a
         ^
Error: Compilation produced 1 error(s); 1 within the --top top hierarchy (or design-scoped)

Cause. The SystemVerilog is not legal. Each error is printed with its file, line and column before the summary line.

Fix. Correct the first error and compile again. Later errors are often caused by the first.

`Top module '…' not found in design`

module top;
  initial $display("hello");
endmodule

ryusim -q compile top.sv --top Top 2>&1 || true

Error: Top module 'Top' not found in design

Cause. No module in the sources has the name given to --top. Module names are case-sensitive.

Fix. Pass the module's exact name, and check that the file that declares it is on the command line.

`unsupported construct`

primitive inv_udp(output y, input a);
  table
    0 : 1;
    1 : 0;
  endtable
endprimitive

module udp_top;
  logic a = 0;
  wire y;
  inv_udp u(y, a);
  initial begin
    #1 $display("y=%b", y);
    $finish;
  end
endmodule

ryusim -q compile udp.sv --top udp_top -o udp_obj 2>&1 || true

udp.sv:11:11: error: unsupported construct: primitive (representation complete; execution support pending)
  inv_udp u(y, a);
          ^
Error: design uses constructs without execution support (--unsupported=error)

Cause. The design uses a construct that parses and elaborates but that RyuSim cannot yet simulate: here, a user-defined primitive. RyuSim rejects such a design at compile time instead of simulating it wrongly. The Compliance Matrix lists what is not yet supported.

Fix. Rewrite that part of the design with supported constructs, or wait for the release that adds it.

--unsupported=warn turns the error into a warning so that you can see every unsupported construct in one compile. It is for triage only. The simulation it builds does not execute those constructs, and its results are wrong:

ryusim -q compile udp.sv --top udp_top -o udp_obj --unsupported=warn 2>&1
./udp_obj/build/udp_top_sim

udp.sv:11:11: warning: unsupported construct: primitive (representation complete; execution support pending)
  inv_udp u(y, a);
          ^
WARNING: unhandled gate primitive 'inv_udp' with 2 ports
RyuSim - Simulation of udp_top
RyuSim: effective root seed = 6680099742810828430 (source: randomly generated)
y=z
Simulation complete. Time: 1

The inverter's output should be 1. It is z because the primitive was never executed.

`typed sim build failed`

Error: typed sim build failed — no legacy re-route (a re-route converts a typed-emitter bug into a silent semantic swap; file the bug instead). First error: <first clang error>

Cause. The C++ that RyuSim generated did not compile. The message quotes the first Clang error.

Fix. If the quoted error is about the environment (a missing program, header or library), fix that and compile again. If the error points into a generated file under obj_dir, it is a RyuSim bug. Report it with the design, or a reduced version of it, as described on the Support page.

A missing library is reported separately, as Error: the simulation build failed for an environment reason, not a RyuSim codegen problem, followed by the linker's cannot find -l<name>. Install the development package that provides the library.

`IR2-DROP`

Error: IR2-DROP — converter failed to represent 1 construct(s); this is a RyuSim bug

Cause. The design compiled without errors, but RyuSim failed to carry some of it into its internal representation. RyuSim stops rather than simulate a design with parts missing.

Fix. Report it on the Support page, with the design and the full compile output.

Simulation

`combinational cycle did not converge`

module loop_top;
  logic a = 0;
  wire b;
  assign b = ~a;
  always @* a = b;
  initial begin
    #1 $display("a=%b", a);
    $finish;
  end
endmodule

ryusim -q compile loop.sv --top loop_top -o loop_obj 2>&1
./loop_obj/build/loop_top_sim 2>&1 || true

warning: combinational cycle through a, b (module loop_top)
RyuSim - Simulation of loop_top
RyuSim: effective root seed = 8824275631837047829 (source: randomly generated)
[ryusim] FATAL: combinational cycle did not converge after 10000 iterations (limit --max-settle-iters) through: loop_top.__ryu_st_1, loop_top.__ryu_st_0

Cause. A loop of combinational logic kept changing within one time step. Here a drives b through an inverter and b drives a back, so the loop never settles. The compile-time warning names the signals in the loop. The simulation exits with status 1.

Fix. Break the loop with a register or a delay. If the loop does settle, but after more than 10000 iterations, raise the limit with ryusim compile --max-settle-iters <n>.

The simulation does not exit

module clock_top;
  logic clk = 0;
  always #5 clk = ~clk;
endmodule

ryusim -q compile clock.sv --top clock_top -o clock_obj 2>&1
timeout 5 ./clock_obj/build/clock_top_sim || echo "exit status $?"

RyuSim - Simulation of clock_top
RyuSim: effective root seed = 4770697983124940420 (source: randomly generated)
exit status 124

Cause. A native testbench runs until $finish is called or no events are left. A free-running clock always has another event, so the simulation never ends. Here timeout stops it after 5 seconds (exit status 124).

Fix. End the test with $finish:

module clock_top;
  logic clk = 0;
  always #5 clk = ~clk;
  initial #100 $finish;
endmodule

ryusim -q compile clock_fixed.sv --top clock_top -o clock_obj 2>&1
./clock_obj/build/clock_top_sim

ryusim compile --max-time is accepted, but in RyuSim 2.1.16 it has no effect: it does not stop the simulation. Use $finish. Under cocotb, the simulation ends when the last test finishes.

An old executable is still in `obj_dir`

ryusim -q compile clock_fixed.sv --top clock_top 2>&1
ryusim -q compile top.sv --top top 2>&1
ls obj_dir/build

clock_top_sim
libclock_top.so
libtop.so
obj
ryu_pch.sh
top_sim

Cause. Two designs were compiled into the same output directory. The executable is named after the top module (<top>_sim), and compiling a second design does not delete the first one's executable. Running obj_dir/build/clock_top_sim here runs the older design.

Fix. Give each design its own directory with -o, or remove the directory before you compile a different design. Recompiling the same design in place is safe: changes to its sources, including `include files, trigger a rebuild.

`Could not load VPI library`

./clock_obj/build/clock_top_sim --vpi-load ./missing_vpi.so 2>&1 || true

RyuSim - Simulation of clock_top
RyuSim: effective root seed = 13548554086147970351 (source: randomly generated)
ERROR: Could not load VPI library: ./missing_vpi.so: cannot open shared object file: No such file or directory

Cause. The file given to --vpi-load does not exist, or the dynamic loader cannot load it or a library it depends on. The text after the path is the loader's own error. The simulation exits with status 1.

Fix. Check the path. If the loader names a missing dependency, add its directory to LD_LIBRARY_PATH.

cocotb

cocotb support comes from the cocotbext-ryusim Python package. The cocotb page covers installation and the Makefile, Python runner and pytest flows. The entries below use this design and Makefile:

module counter(input logic clk, input logic rst, output logic [3:0] q);
  always_ff @(posedge clk) q <= rst ? 4'd0 : q + 4'd1;
endmodule

SIM ?= ryusim
TOPLEVEL_LANG = verilog
VERILOG_SOURCES = $(PWD)/counter.sv
COCOTB_TOPLEVEL = counter
COCOTB_TEST_MODULES = test_counter
include $(shell cocotbext-ryusim-config --makefiles)/Makefile.sim

`cocotbext-ryusim-config: No such file or directory`

make: cocotbext-ryusim-config: No such file or directory
Makefile:6: /Makefile.sim: No such file or directory
make: *** No rule to make target '/Makefile.sim'.  Stop.

Cause. cocotbext-ryusim is not installed in the Python environment make runs in, or that environment's bin directory is not on PATH.

Fix. Activate the virtual environment you installed it in, or install it:

python3 -m pip install cocotbext-ryusim

`find_libpython was not able to find a libpython`

…/cocotb_tools/makefiles/Makefile.inc:117: ***

find_libpython was not able to find a libpython in the current Python environment. Ensure
the Python development packages are installed. If they are installed and find_libpython
is not finding the path to libpython, file an upstream bug in find_libpython; then
manually override the LIBPYTHON_LOC make variable with the absolute path to libpython.so
(or python.dll on Windows).
.  Stop.

Cause. cocotb loads Python into the simulation as a shared library, libpython. A stock Ubuntu 24.04 image has the Python interpreter but not that library.

Fix. Install the Python development package, which brings libpython with it. On Debian and Ubuntu:

sudo apt install python3-dev

`Couldn't find makefile for simulator: "ryusim"`

SIM ?= ryusim
TOPLEVEL_LANG = verilog
VERILOG_SOURCES = $(PWD)/counter.sv
COCOTB_TOPLEVEL = counter
COCOTB_TEST_MODULES = test_counter
include $(shell cocotb-config --makefiles)/Makefile.sim

make -f Makefile.stock 2>&1 || true

…/cocotb_tools/makefiles/Makefile.sim:93: *** Couldn't find makefile for simulator: "ryusim"! Available simulators: activehdl cvc dsim ghdl icarus ius modelsim nvc questa questa-compat questa-qisqrun riviera vcs verilator xcelium.  Stop.

Cause. The Makefile includes cocotb's own Makefile.sim, which does not know RyuSim.

Fix. Include the one from cocotbext-ryusim-config --makefiles instead, as in the Makefile above. It hands every other SIM to cocotb's Makefile.sim, so one Makefile still works with other simulators.

`Unable to locate command >ryusim<`

make RYUSIM_BIN_DIR=/opt/no-ryusim-here 2>&1 || true

…/cocotbext/ryusim/makefiles/simulators/Makefile.ryusim:25: *** Unable to locate command >ryusim<. Stop.

Cause. The Makefile flow looks for ryusim in RYUSIM_BIN_DIR when it is set, and on PATH when it is not. It found no executable there.

Fix. Put the directory that holds ryusim on PATH, or set RYUSIM_BIN_DIR to it.

`Simulator 'ryusim' is not in supported list`

python3 -c 'from cocotb_tools.runner import get_runner; get_runner("ryusim")' 2>&1 || true

ValueError: Simulator 'ryusim' is not in supported list: icarus, questa, questa-qisqrun, ghdl, riviera, activehdl, verilator, xcelium, nvc, vcs, dsim

Cause. cocotb's Python runner learns about RyuSim when cocotbext.ryusim is imported. The script called get_runner("ryusim") without importing it.

Fix. Add import cocotbext.ryusim before the call to get_runner.

`ERROR: ryusim executable not found!`

env PATH=/opt/no-ryusim-here "$(command -v python3)" -c 'import cocotbext.ryusim; from cocotb_tools.runner import get_runner; get_runner("ryusim")' 2>&1 || true

Cause. The Python runner found no ryusim on PATH.

Fix. Put the directory that holds ryusim on PATH before you start Python or pytest.

`hdl_toplevel argument is required`

python3 -c 'import cocotbext.ryusim; from cocotb_tools.runner import get_runner; get_runner("ryusim").build(sources=["counter.sv"])' 2>&1 || true

Cause. The RyuSim runner always compiles with --top, so build() needs the top module.

Fix. Pass it: build(sources=["counter.sv"], hdl_toplevel="counter").

`cocotbext-ryusim requires cocotb>=2.1,<2.2`

ImportError: cocotbext-ryusim requires cocotb>=2.1,<2.2, and a cocotb internal it depends on is missing (<original error>). Check the installed version with `pip show cocotb`.

Cause. cocotbext-ryusim 0.1.0 requires cocotb 2.1 (cocotb>=2.1,<2.2). pip installs a matching cocotb with it, but a later install can replace it with another version.

Fix. Install a cocotb 2.1 release in the same environment:

python3 -m pip install "cocotb>=2.1,<2.2"

`No GPI_USERS specified`

ryusim -q compile counter.sv --top counter -o counter_obj 2>&1
env -u GPI_USERS ./counter_obj/build/counter_sim \
  --vpi-load "$(python3 -m cocotb_tools.config --lib-name-path vpi verilator)" 2>&1

RyuSim - Simulation of counter
RyuSim: effective root seed = 5690357545972048511 (source: randomly generated)
     -.--ns ERROR    gpi                                ../gpi/GpiCommon.cpp:188  in gpi_load_users                  No GPI_USERS specified, exiting...
Simulation finished. Time: 0

Cause. The simulation executable was started by hand with cocotb's VPI library, outside the Makefile flow or the Python runner. Those set GPI_USERS, which tells cocotb which Python library to load. Without it cocotb does not start and no test runs.

Fix. Run cocotb tests through make, the Python runner or pytest.

`PYGPI_PYTHON_BIN variable not set`

env -u PYGPI_PYTHON_BIN \
  GPI_USERS="$(python3 -m cocotb_tools.config --libpython);$(python3 -m cocotb_tools.config --pygpi-entry-point)" \
  LD_LIBRARY_PATH="$(python3 -m cocotb_tools.config --lib-dir)" \
  ./counter_obj/build/counter_sim \
  --vpi-load "$(python3 -m cocotb_tools.config --lib-name-path vpi verilator)" 2>&1

     -.--ns ERROR    pygpi                              ..ib/pygpi/embed.cpp:41   in get_interpreter_path            PYGPI_PYTHON_BIN variable not set. Can't initialize Python interpreter!

Cause. cocotb 2 embeds the Python interpreter named by PYGPI_PYTHON_BIN. The Makefile flow and the Python runner set it to the interpreter they run under. A hand-started simulation has to set it itself.

Fix. Use make, the Python runner or pytest. If you must start the executable yourself, set PYGPI_PYTHON_BIN="$(python3 -m cocotb_tools.config --python-bin)" along with GPI_USERS and LD_LIBRARY_PATH as above, and the test module and top level in COCOTB_TEST_MODULES and COCOTB_TOPLEVEL.

Troubleshooting

Messages

Toolchain

clang++ not found on PATH

zlib development library (libz.so) not found

ninja is not on PATH

cmake: not found

genhtml command not found

Compile

File does not exist

Compilation produced 1 error(s)

Top module '…' not found in design

unsupported construct

typed sim build failed

IR2-DROP

Simulation

combinational cycle did not converge

The simulation does not exit

An old executable is still in obj_dir

Could not load VPI library