Before you ask for help, which of the usual mistakes have you already checked?
Almost every beginner failure in this course is a repeat. The same mistyped command, the same missing tab and the same silent testbench return in every cohort. This lesson collects eighteen repeats into one checklist, grouped by stage.
The checklist works backwards from the symptom. Read the first error literally, as Troubleshooting Table teaches, and let it point at one group below. Work that group's rows in order before changing anything.
The picture below maps the six groups onto the loop: workstation, tools, simulation, verification, automation and hand-off, three checks each. The dashed arrow is the point: a found mistake sends you back for a fix and a rerun.
Check 7 below is the model for all eighteen rows: the compiler cannot find the named module. The transcript shows the real tool output for that mistake, one wrong letter in the top name.
# captured terminal output
$ iverilog -g2012 -s mini_control -o build/top.vvp rtl/mini_controller.sv
error: Unable to find the root module "mini_control" in the Verilog source.
: Perhaps ``-s mini_control'' is incorrect?
1 error(s) during elaboration.
[exit status 1]This output came from Icarus Verilog 13.0 on macOS. The tool names the missing module, repeats your flag, and asks whether the flag is incorrect. The design is fine; the command names nothing real.
The command is wrong. The design file holds mini_controller and the flag asks for mini_control, which exists nowhere. Check the spelling of the -s name against the module name in the source before suspecting the design.
The fix matches -s to the testbench module and reruns. Message first, owning row second, fix and rerun third: that is how every row below works.
Replace one recipe tab with two spaces and rebuild. Make stops with Makefile:2: *** missing separator. Stop. and exit status 2. The full captured output, with the fix, is in the Troubleshooting Table, where this is case 5. The message names the file and line: a missing separator means a recipe without a leading tab. Start every recipe with a tab, and set the editor to keep tabs in Makefiles.
Work each group only when the symptom points at it. Every row gives the symptom, the fix, and the lesson that teaches the full story.
1. `command not found` for a tool you just installed. The shell cannot see it. Fix: run make check-tools, compare against the version record, reinstall what is missing. Taught in Installing and Checking Tools.
2. `No such file or directory` for a path that looks right. Wrong folder. Fix: print the folder, list it, move to the project root, rerun. Taught in Files, Paths and Layout.
3. Build outputs or waveforms committed, or nothing committed. Stale files bloat copies; uncommitted sources can vanish. Fix: ignore build/ and waveforms; commit sources, specs, scripts. Taught in Git: Save, Compare, Undo.
4. Icarus `-Wall` warns of missing time units. A file without a time scale borrows timing silently, measured on Icarus 13.0 on macOS. Fix: put a time scale atop every file. Taught in Compile, Elaborate, Simulate, Synthesize, Lint.
5. Yosys `check` exits 0 despite an undriven wire. Plain check misses it, measured with Yosys 0.69+post on macOS. Fix: run check -assert, which exits 1. Taught in First Synthesis Check.
6. Verilator pragma error on a plain comment. A comment starting with verilator reads as a pragma, measured with Verilator 5.048 on macOS. Fix: reword the comment. Taught in Lint with Verilator.
7. `Unable to find the root module`. The -s flag names nothing that exists, as above. Fix: match -s to the testbench module exactly. Taught in First Simulation.
8. Syntax error on `before` or `edge`. Both are SystemVerilog keywords, measured with Icarus 13.0 on macOS. Fix: rename to prev, idx or similar. Taught in Simulation Code vs Synthesizable Code.
9. A verdict with no waveform. Missing dump calls. Fix: keep dump calls in testbenches you intend to view. Taught in Waveforms with GTKWave.
10. A verdict with no checks behind it. It passes on broken code. Fix: mutate the design; the test must fail on every real bug. Taught in Tests That Can Fail.
11. Random tests pass on one seed. One seed covers one path. Fix: run several seeds and record them. Taught in Random Stimulus and Seeds.
12. Expectations copied from the design. The test repeats the code's mistakes. Fix: write expectations from the spec; cross-check with the golden model. Taught in Self-Checking and Golden Model.
13. `missing separator` from Make. Spaces instead of a tab, as above. Fix: start every recipe with a tab. Taught in Makefile for the Loop.
14. A red run ignored. The exit status carries what the log buries. Fix: check the status; require one verdict line per run. Taught in Exit Codes and Pass Markers.
15. Green here, red on a fresh machine. No versions recorded. Fix: keep a versions file; compare before debugging. Taught in Pinning Tool Versions.
16. A README with no run commands. Admired but unrunnable. Fix: add exact commands retyped from a clean checkout. Taught in The Release Package.
17. Constraints copied from another block, or no clock line. The numbers fit someone else. Fix: write each file from its own clock and ports. Taught in Reading a Constraints File.
18. Generated files shipped, or two testbenches. Stale outputs disagree with the build. Fix: ship sources plus a manifest. Taught in The Release Package.
Treating the list as a substitute for the first error. Scanning all eighteen rows while ignoring the message turns a two-minute fix into an afternoon. Read the first error literally first; the checklist only tells you what that error usually means.
Rule: read the first error literally, then check the usual mistakes in its group before changing anything.
The listing below is an illustrative repository offered for audit: six usual mistakes hide in it. Find all six before reading the answer.
// not-run: illustrative repository listing, not a real project
counter/
rtl/counter.sv
tb_counter.sv
tb_counter_final.sv
build/sim.vvp
wave.vcd
makefile
# top of makefile: recipes indented with two spaces
sim:
iverilog -g2012 -s tb_counter -o build/sim.vvp rtl/counter.sv tb_counter.sv
# end of tb_counter.sv
$finish;This listing is the audit exercise: a small project folder with six planted problems and nothing else to blame.
No version record: add the tools file. No README: add what the design is plus run commands. Two testbench copies: keep one. Space-indented makefile recipes: rename to Makefile and retab. Tracked build folder and waveform: ignore generated files. Bare finish with no verdict: add self-checks with one verdict and a loud stop on mismatch.
edge. What happened, and what do you rename it to?The name collides with a SystemVerilog keyword, so the compiler never treats it as your identifier. Rename it to a word the language does not own, such as idx, and rerun. Row 8 owns this one.
check exits 0 on your design, yet simulation shows an undriven wire. What do you add, and why does the bare command mislead?Add the asserting form, check -assert, which exits 1 on the undriven wire. The bare form reports the warning and still exits 0, so a scripted loop reads success where a human would have paused. Row 5 owns this one.
Most beginner failures are repeats: read the first error literally, then work the one checklist group it points at.
Each row pairs a symptom with a fix and the lesson that teaches it, from missing time scales to copied constraints.
Fix one thing and rerun before touching anything else, so every change answers exactly one question.