Troubleshooting

kipcb: could not find a Python with KiCad's pcbnew module Install KiCad 9. If it's installed somewhere unusual, point KIPCB_PYTHON at a Python that can import pcbnew: on macOS /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3, on Windows C:\Program Files\KiCad\9.0\bin\python.exe (or set KIPCB_KICAD_ROOT to KiCad's install folder).

kipcb is not found in Claude Code The plugin's bin/ folder is only on PATH while the plugin is enabled. Start a new session after installing. Outside Claude Code, run bin/kipcb from the repo.

Freerouting: Java too old / not found Freerouting 2.1 needs Java 21+, and newer versions need Java 25. Run java -version, install a newer JRE (macOS: brew install --cask temurin; Windows: winget install EclipseAdoptium.Temurin.21.JDK), then kipcb setup-router again.

Routing leaves connections unrouted kipcb already retries with different strategies and runs a completion pass. If connections still fail: - give the board more room (larger width/height, or "spacing": "roomy") - spread crowded groups, or use place hints so ICs face their partners - move to 4 layers for dense boards (fine-pitch QFNs like the RP2040 currently route better on 2) - run kipcb route <project> --attempts 6 to try more strategies

Each run is remembered, so later boards start with strategies that worked.

DRC errors after routing Run kipcb drc <project> for details. Clearance or edge errors usually mean a part sits too close to the edge or to another part; adjust placement and rebuild. Silkscreen warnings are cosmetic.

Noise check FAILs See the table in layout-guidelines.md. The usual fix is a near hint on the exact supply pin for its decoupling cap, or more board room so routes stay on the top layer.

The schematic or board changed after I edited it in KiCad kipcb build regenerates the KiCad files from the spec, which overwrites hand edits. Iterate through the spec first, then polish in KiCad at the end.

A part isn't in KiCad's libraries See "Custom parts" in spec-format.md (stock equivalents, easyeda2kicad, or a hand-made footprint).

Not routing: U1 is outside the board outline A part didn't fit and was parked beside the board. Make the board larger, use "spacing": "normal" (or "compact") on small boards, or free up fixed positions, then rebuild. Routing refuses to start in this state, because it could never succeed.

regulator heat warning A linear regulator turns (Vin − Vout) × current into heat. Use a bigger package (SOT-223 instead of SOT-23), lower the input voltage, or switch to a buck converter.

kipcb ref shows an older knowledge base than you built A locally built base (knowledge.json in kipcb's data folder: ~/.local/share/kipcb on macOS, %LOCALAPPDATA%\kipcb on Windows; from pcb-knowledge's pkb install) takes priority over the copy shipped with the plugin.

Windows: \r: command not found or bad interpreter A script was checked out with Windows (CRLF) line endings. Reinstall the plugin (claude plugin uninstall viaduct@viaduct, then install again); the repository pins scripts to LF, so a fresh install fixes it.

Windows: Claude Code can't run commands Claude Code on Windows needs Git for Windows (winget install Git.Git). Restart Claude Code after installing it.

Something else Run kipcb doctor and include its output when you open an issue.