When a run fails
Read the card, ask Nelix Agent for a diagnosis, and accept a repair only when you agree with it.
On this page
Read the card firstTry it on purposeDebug with Nelix AgentThree rules the lab keepsKinds of failureA failed run is the normal way to learn. The lab is built to show you what went wrong.
Read the card first#
A failed stage card already tells you three things: what failed, the tool's own evidence, and a proposed next step. That reading does not use AI credits.
Try it on purpose#
- In the project folder, open the design.
nanoandviare both in the terminal. - Change one line so the design is wrong. For example, turn the add into a subtract.
- Run the simulation. It fails and prints the run id.
- Open Overview. The Simulate card shows what failed, the evidence and the next step.
nano rtl/top.sv
nelix testDebug with Nelix Agent#
- On the failed card, choose Debug with Nelix Agent. This uses AI credits from your plan.
- Read the diagnosis. It is based on the source that run used, not on whatever is in the file now.
- If Nelix Agent proposes a repair, review the change. Nothing is written to your design until you accept it and then merge it.
- Accept the repair, then Merge it. Merging writes the change into your file, keeps a backup and runs your test again.
- That test inside Merge is a check, not a Simulate run, so Overview still shows the old failed Simulate. Run Simulate from Overview to record the new result.
- Changed your mind? Undo the fix on the same page puts your file back exactly as it was before the merge. It asks first.
The analysis can take a few minutes. If the page loses its connection to the lab for a moment, it keeps following the analysis; you do not need to press anything. If the lab was restarted while it worked, the page says so and Try again starts it again.
A merged repair changes only the lines whose code changes: your comments, blank lines and spacing stay as you wrote them, and each changed place gets a short comment above it (Nelix Agent fix (date): why, and was: the old line), so you can always see what was changed.
When Synthesize or Build the chip stops, the note on the Overview names the real cause: the build ran out of memory (the design is too big for one lab run), the cells do not fit on the chip (with a suggested die size for Build settings), your project storage is full, the VHDL synthesis tool could not handle a line, timing failed at the end of the build (the note names the build's last step and the corners with setup or hold violations), or the tool's own error. "The cells do not fit" is said only when placement really stopped there, not when the tools merely warned about the placement density. A build that stopped after routing can be finished with Re-run from a stage → After routing on its report, instead of building everything again.
The Ask Nelix Agent button on a failed card is different: it explains what failed in that stage and suggests a next step, without proposing a change.
From the terminal, the same diagnosis is nelix debug followed by the run id:
nelix debug TST-20261005-0001Three rules the lab keeps#
- A proposed repair is checked against the test, in a separate copy of your project, before you can accept it. You may see the change while that check is still running; it is marked as not tested yet. The check does not use AI credits.
- A repair does not rewrite your test to make it pass.
- Your working design is not changed unless you merge the repair.
Kinds of failure#
| What you see | Usual cause |
|---|---|
| A syntax or elaboration error, with a file and line | A mistake in the code |
| An assertion failed, with expected and seen values | The design does not do what the test expects |
| Timed out | A test waiting for something that never happens, or a build that needs more than its time limit |
| Timing not met, on a build | A path in the design is slower than the clock allows. See Timing explained |
You can also ask about a failure in Design Chat.
Something unclear or missing? Send feedbackSign in and use Feedback to tell us.