Public

Troubleshooting

Fault-isolation entry point for digital flow, environment, DRC, LVS, timing, and tool failures.

Scope

This page is the fault-isolation entry point. It routes a symptom to the smallest useful investigation. Detailed DRC/LVS and tool-crash remedies are on the linked pages.

First response

  1. Preserve the failed run directory, exact command, resolved configuration, first error, logs, report databases, template tag, Nix lock, and PDK/tool versions. This is an inferred evidence set from successful reduced-case and local-versus-CI investigations. Reduced-case evidence (Discord) Environment evidence (Discord)
  2. Decide whether the fault follows the design, the machine, or the pinned environment. A recorded local KLayout XOR failure did not occur in GitHub CI, so the investigation compared locks, tested the vanilla template, and inspected the preceding Magic GDS. Evidence (Discord)
  3. Reduce the failing object. KLayout was run on one failing cell with the same DRC deck to create a smaller case. Evidence (Discord)
  4. Do not discard a crash as normal. OpenROAD segfaults were explicitly described as upstream bugs that should be reported with a reproducer. Evidence (Discord)

Symptom routing

  • Yosys check failure: read the first check detail in yosys-synthesis.log and reports/pre_synth_chk.rpt, then reduce to a Yosys-only case. Evidence (Discord)
  • Post-route hold failure: inspect the post-PNR summary and the failing corner's min.rpt; then use the ECO procedure and route the inserted cells. Evidence (Discord) Routing evidence (Discord)
  • DRC slow or apparently hung: check CPU, memory, log timestamps, PDK version, and connectivity setup before changing the rule deck. PDK 1.4.1 fixed one connectivity problem and reduced a tested run from hours to about 1.5 hours. Evidence (Discord)
  • LVS count or pin mismatch: inspect lvs.netgen.rpt, confirm that layout and Verilog are from the same run, then check LEF labels and hierarchy. Report evidence (Discord) Stale-netlist evidence (Discord)
  • Magic open-file limit: use a template/LibreLane version with locking disable. The fix shipped in Template 1.5.2 on 2026-06-08. Evidence (Discord)

Status boundaries

  • Obsolete guidance: conn_drc false was a diagnostic bypass for very slow KLayout connectivity construction. It loses connectivity information and can create worst-case false positives. A later PDK fixed the recorded connectivity problem. Bypass (Discord) Warning (Discord) Fix (Discord)
  • Open question: A report that a tool is “stuck” is not enough to separate a hang from a slow connectivity or extraction step. Preserve complete logs and resource use before classifying the fault. This is an inference from the multi-hour KLayout case. Evidence (Discord)

Sources

  • 1443614548182568971 — 2025-11-27T14:48:49.348+00:00 — tnt (@246tnt); 1443614636464148552 — 2025-11-27T14:49:10.396+00:00 — tnt (@246tnt) — reduced single-cell KLayout run. Evidence 1 (Discord) Evidence 2 (Discord)
  • 1512740258649870336 — 2026-06-06T08:49:43.017+00:00 — Leo Moser (mole99) (@mole99); 1512912751641628845 — 2026-06-06T20:15:08.551+00:00 — RebelMike (@rebelmike) — Nix and local-versus-CI diagnosis. Evidence 1 (Discord) Evidence 2 (Discord)
  • 1443385708302831667 — 2025-11-26T23:39:29.669+00:00 — Tim 'mithro' Ansell (@mithro_) — report OpenROAD segfaults upstream. Evidence (Discord)
  • 1440439686526144552 — 2025-11-18T20:33:03.343+00:00 — aedancullen — Yosys check locations. Evidence (Discord)
  • 1445872535160885409 — 2025-12-03T20:21:15.395+00:00 — Lofty (@ravenslofty); 1445910109375959070 — 2025-12-03T22:50:33.786+00:00 — Trevor Peyton (@trev5514) — timing and ECO routing. Evidence 1 (Discord) Evidence 2 (Discord)
  • 1446446102734962835 — 2025-12-05T10:20:24.561+00:00 — Leo Moser (mole99) (@mole99) — PDK 1.4.1 KLayout connectivity fix. Evidence (Discord)
  • 1446665494374646050 — 2025-12-06T00:52:11.604+00:00 — bailey (@bailey8889); 1446673863537590324 — 2025-12-06T01:25:26.968+00:00 — bailey (@bailey8889) — Netgen report and stale netlist. Evidence 1 (Discord) Evidence 2 (Discord)
  • 1513546884726259844 — 2026-06-08T14:14:57.66+00:00 — Leo Moser (mole99) (@mole99) — Magic file-locking fix. Evidence (Discord)
  • 1445398457929171079 — 2025-12-02T12:57:26.575+00:00 — Leo Moser (mole99) (@mole99); 1445398872594579530 — 2025-12-02T12:59:05.439+00:00 — Leo Moser (mole99) (@mole99) — conn_drc false bypass and warning. Evidence 1 (Discord) Evidence 2 (Discord)