12 Troubleshooting

For you when a command, a check or EasyEDA fails. Find the symptom – often the message as it is printed – and the table gives its cause and the fix. Start with edakit doctor. The short way: the steps.

Symptom	Cause	Fix
easyeda_bridge_status: not connected	no server ran yet, or EasyEDA was restarted	the first tool call starts the server; Auto-Connect connects within seconds. Otherwise MCP Bridge → Connect; after a re-import the menu may be missing – restart EasyEDA, Auto-Connect stays on
MCP tools missing in the session	the server did not start (Node not 24, npm failed)	bash edakit/easyeda/mcp-server.sh doctor; then /mcp → easyeda (only you can reconnect, not Claude)
port 49620 busy, "address in use"	an orphaned server (started through npx, or a crashed session)	pgrep -af easyeda-mcp-pro, ss -ltnp \| grep 4962, end the stale one (tell other sessions)
"timed out after 15000ms"	the server that sent the call runs with the default 15 s	edakit doctor names the servers whose BRIDGE_TIMEOUT_MS differs, with their PIDs; end them (tell other sessions); they restart with BRIDGE_TIMEOUT_MS=120000 from mcp-server.sh
DRC, pour fill or export hang; EasyEDA hardly busy	EasyEDA runs throttled because its window is covered	save, quit, start unthrottled (EasyEDA without background throttling, 2.6); edakit doctor shows it
"bad option: --no-sandbox" when starting EasyEDA	ELECTRON_RUN_AS_NODE inherited from VS Code	env -u ELECTRON_RUN_AS_NODE …
every DMT_* call returns null	EasyEDA shows its start page (focus tab_page1)	open the project; edakit reopens it by its remembered UUID
"project … is in none of EasyEDA's project folders"	no local project of that name	create it in EasyEDA (File → New → Project) with the name of [project] name
answers contain [MaxDepth], DRC details empty; edakit doctor: "extension ignores maxDepth"	a bridge extension older than 1.7.0	import the one of the pinned server (the bridge extension, 2.5): uninstall old, import, restart; edakit doctor says "return depth: answers deeper …" when the new one runs
edakit doctor: "bridge extension … against server …" or "method registry … differs"	the extension is of another easyeda-mcp-pro version than the pinned server	copy the extension of the pinned server (mcp-server.sh extension --copy ., the bridge extension, 2.5) and import it
PCB_Drc.check returns null / undefined	the PCB tab counts as inactive	edakit switches to the start page and back; or click the PCB tab once
DRC: many "Connection Error" right after routing	DRC on the unsaved state after many API changes	route all, silk apply and the gate reload and run the DRC once more by themselves; by hand edakit route reload, then edakit route drc – reported 320 → 0
DRC: "Netlist Error – Import Changes"	schematic and PCB differ, or a schematic part lacks its PCB part's Channel ID (placed before edakit wrote it, E-2)	differences named: edakit pcb parts --write or pcb nets --write; none: edakit route drc writes the Channel IDs, reloads and checks again. Only if it then says "EasyEDA waits for the import acknowledgement" (exit 3): open Design → Import Changes once in the GUI (shows "no changes")
pour fill fails: "Cannot read properties of undefined (reading 'length')"	a free pad (tooling hole) is in the PCB	edakit removes tooling holes before filling; by hand: edakit pcb tooling after the fill
"pour … not filled: A previous native PCB copper rebuild ended without complete verification"	the bridge refuses every rebuild after one it could not verify (readback-mismatch), until EasyEDA restarts – until 1.6.0 a net's second pour in one call (M-10)	restart EasyEDA, then edakit route fill (the PCB is saved) and edakit route drc; edakit fills a net's fresh pours in one call, which 1.7.0 verifies
"pours not filled: GND TOP (…) no-copper … the bridge's, not the board's (easyeda-mcp-pro …, M-13)"	EasyEDA's copper engine fills nothing after pads, vias or tracks were changed through the API until the PCB is loaded again (desk-led); edakit reloads it before each fill since this was found, so it should not come any more	the PCB is saved: edakit route fill (reloads, one pour per call), then edakit route drc (7.6). Fails that as well: restart EasyEDA, route fill once more; then report it with the message
"pours not filled: GND BOTTOM (…) no-copper … the board's, not the bridge's"	the net has no pad, via or track on that layer – EasyEDA drops a pour that touches none (7.6)	a pad or via of the net there, or the layer to another net in [[pours]] of the board file
"focus lost" / "获取器件关联的所有引脚失败" (pins not readable)	another tab became active (a click, another script)	scripts get the tab back or abort; never run two EasyEDA jobs at once; claim EasyEDA
schematic texts come back after a reload	SCH_PrimitiveText.delete is not saved	edakit deletes through another primitive class (the schematic API, 9.3)
"schematic … could not be renamed" (modifySchematicName false)	after a start of EasyEDA the project tree in the left panel was never shown – EasyEDA renames only what it lists	open the project tree in EasyEDA's left panel once, run again (E-17; the editor state, 9.2)
renaming a schematic renamed another one	modifySchematicName acts on the active schematic	edakit activates first and checks every name; never delete on a mismatch
edakit schematic check suddenly reports a pin on two nets in the template	a bridge older than 1.9.0 lists a pin on a second net with no primitive there while another schematic of the project is open (M-11)	edakit doctor: server and extension 1.11.0 (2.4, 2.5); with them still there – regenerate the template (schematic create --save), and when its last step says the save differs, the drawing at that pin has to change
schematic check reports saved: … unsaved changes in EasyEDA	the schematic's tab holds changes not saved; the check reads it as drawn, not as saved	save it (schematic create --save) or close the tab without saving
copy refuses: "belongs to board"	the PCB is linked to the target	correct: use edakit schematic layout, which syncs in place
copy: "copySchematic copied something else than 'generated_main': 19 parts instead of 17 …, what EasyEDA made: page 'Christmas bell ESP32 THT template' …"	EasyEDA copied another schematic than the one named – once another project's, opened earlier in the same EasyEDA (copy and lay out, 6.3)	the copy is deleted (left where it is no free schematic of the open project); restart EasyEDA, or build the board schematic with edakit schematic layout, which copies nothing
schematic create: "! schematic … is named 'LED bar template', not 'generated_main' – renaming it back"; "! a panel of the project is named 'generated_main'"	the page title reached the schematic's name, in a project just created (generate the template, 6.1)	edakit puts the name back; rename or delete the panel in EasyEDA, edakit leaves it
Freerouting leaves nets open	order dependence, crowded pads, rules	route all retries reshuffled; more passes; more room in the plan; a power plane; lower clearance only within EasyEDA's DRC
route check: a plane net open, its SMD pads on the other side in groups of their own	Freerouting connects no pad to a plane with a via	fanout = true on the plane in [[pours]] (routing with Freerouting, 7.5)
route check / GEO.spacing: "R22.2 (N3) – R37.1 (N2): 0.090 mm apart on TOP, below the clearance …"	two parts placed with their pads closer than the routing clearance; Freerouting cannot move a pad	move or turn one of them in [place] (fix it there if the auto-layout put it), then pcb apply and route all again
route check / GEO.spacing: "C2.2 (GND) – D1.2 (VIN): 0.300 mm apart on TOP, below the paste gap 0.400 mm"	SMD pads of two parts on an assembled side so close that the stencil leaves only a thin web between their prints – the paste can bridge in reflow	spread or turn one of them in [place], then pcb apply and route all again; a pair close on purpose gets accept GEO.spacing with the reason
GEO.pour: "TOP: 47 % copper, largest copper-free circle Ø 9.7 mm at (-19.0, 111.7) mm"	EasyEDA dropped the pour pieces that touch no pad of the pour net, or the pour was not filled (again) after the last copper change	give the area a net that reaches it (a second pour net with pour_regions, or a pad or via of the pour net there), route pours, export and gate again; bare on purpose: accept the warning with its reason
GEO.pour: "TOP: 6 % copper, largest copper-free circle Ø 8.2 mm at (5.0, 4.5) mm – the board file pours nothing on this seen face"	the face people see ([looks] visible, both faces without [looks]) has no pour in [[pours]] – left out, or the only pour went to the other side	pour that face with a net that has pads or vias there ([[pours]], pour_only, pour_regions), route pours, export and gate again; a face meant to stay bare: accept the warning with its reason
GEO.pour: "TOP: 1 piece without pad, via or hole: 16.2 mm² around (10.5, 4.5) mm"	an island kept by a fill with islands (stitching) whose second fill did not run, or copper drawn by hand	connect it with a via or a track, or delete it; fill the pours again without islands
GEO.ring: "D31.1: 0.130 mm on TOP and BOTTOM (hole Ø 0.80 mm)"	the pad leaves less copper around the hole than JLCPCB's minimum ring (0.18 mm; a via 0.05 mm) – often a hole widened for the lead (GEO.hole) on a footprint whose pitch has no room for a larger pad	a larger pad or a smaller hole as far as GEO.hole allows; at a tight pitch another footprint or part; a ring the fab confirmed: accept GEO.ring on the part with the reason
GEO.spacing: "J1.2 – via at (3.00, 12.05): 0.398 mm apart, below 0.45 mm"	two plated holes closer edge to edge than JLCPCB's hole-to-hole spacing (0.45 mm with a component hole, 0.2 mm between vias)	move the via or the part, or a smaller hole where GEO.hole still passes
route check / GEO.spacing: "J1.1 (VIN) – via GND at (84.00, 9.70): 0.30 mm apart on BOTTOM, the solder side of J1, below hand_solder_keep_mm 0.5"	a via or a pad of another net next to a joint soldered by hand (bom: false), on the side the iron works on – at an SMD pad the side its part sits on ("the side D1 sits on")	a via: route all again – the DSN keeps vias away from the joints; a pad: move or turn one of the two parts in [place]; a pair close on purpose gets accept GEO.spacing with the reason
route check / GEO.spacing (warning): "D1.2 (VIN) – via VIN at (77.20, 13.25): 0.10 mm apart on TOP, an assembled side, below smd_via_keep_mm 0.3 (vias untented)"	an open via ([order] vias = "untented") next to an SMD pad the assembler reflows, of any net – it draws the solder off the joint	route all again – the DSN keeps vias away from these pads –, move the via by hand, or tent the vias; a via that must stay: accept GEO.spacing on the part or net with the reason
route check / GEO.under (note): "C2: a track of VIN passes between its pads (C2.1 +5V, C2.2 GND) on TOP, 0.30 mm from a pad of another net"	Freerouting ran a track through the space between the two pads of a small chip part (0402 to 1206), on its side – a shifted part or flowing solder bridges it	move or turn the part in [place] so that the track leaves its pad outward, then route all again; a track that must pass there: accept GEO.under on the part or net with the reason
GEO.spacing (pad clearance, paste gap, hand-soldered joints): "… is not the PCB any more – … moved or changed since"	a part moved, turned or got another net after the last route read	edakit route read (or route all), then the gate again
route dsn stops: "… no room for a fanout via"	foreign pads, the edge, a hole or a keep-out around that pad	more room next to the pad in the plan, or a windows entry for its part in the keep-out
pcb pour stops: "pour_regions – the outlines … come from the routing"	pour_regions and no board file or SES yet	edakit route all (it pours at its end), or route read and route route first
"… its pour at (x, y) mm lies inside the pour of …"	a net's area is enclosed by another net's area on a shared layer – that outline would need a hole	the preview shows where: route so that the outer net does not enclose it, or leave the inner net's pour off that layer
route check: a pour-only net open in groups	tracks of other nets cut its pour into islands	the preview shows the computed pour and where it is cut: a wire keep-out on that layer where the tracks cut it, or more room between the pads there
Freerouting routes nothing in part of the board	concave outline as boundary	edakit uses a rectangle + keep-outs; if you write your own DSN, do the same
tracks appear where a wire keep-out should be	stale DSN	route writes the DSN fresh every time; route check uses the same config
"outline contains arcs"	outline drawn by hand with arcs	draw it with edakit pcb apply (arcs as point lists)
GEO.mark: "'+' at (-20.2, 92.5) mm: nearest pad D19.1 is cathode"	the footprint prints its "+" at the pad the parts entry calls the cathode – the print or the roles are wrong	compare the footprint with the datasheet: roles wrong → correct them in the parts entry; print wrong → put the anode's net on the pad with the "+" and give that pin the role anode (library footprints, 4.4), or another footprint; a decorative cross: accept GEO.mark on the nearest part
GEO.silk: "TOP: edakit's own print … off the solder-mask openings – 0.165 mm² in 1 spot: (19.1, 9.0) mm at C2.1"	a part or a via moved after silk apply, and a designator, text or artwork now lies on a pad	edakit silk apply after the last routing, then the gate again
GEO.silk: "silk_strings_main.json exists, silk_footprints_main/ does not"	silk apply of an older edakit: the gate cannot tell edakit's print from the footprints'	edakit silk apply once
GEO.silk: "R53: silkscreen on its solder-mask openings – JLCPCB clips it there"	the footprint's own frame or mark reaches over the pad's mask opening	correct the footprint, or accept the warning (JLCPCB clips the print there)
GEO.silk: "TOP: … mm² beyond it"	footprint print over the board edge (a connector's outline), or a frame drawn on the edge	correct the footprint or the drawing, or accept the warning; JLCPCB's DFM says "silkscreen outside board"
GEO.silk: "R21: no visible designator, no group label, not in [silk] unlabelled"	silk apply found no room for it ("without room"), or it was hidden	more room, a group label, or [silk] unlabelled = { R21 = "…" } with the reason
silk apply / silk preview: "R4: fixed designator on a pad (top) – 0.42 mm² of its box within 0.15 mm of a solder-mask opening" (or "beyond the printable board", "R4 / START: fixed designator on the text")	the spot in [silk.place] lies on a pad, over the edge or on another text – often after its part moved	move the row's x, y (plan mm) or turn it with rot, check with edakit silk preview offline, then silk apply; or drop the row and let silk apply find a spot
GEO.silk: "pcb.json without the designators"	an export by an older edakit, checked with --offline	edakit fab without --offline (or the gate with --eda)
GEO.silk: "BOTTOM (visible): D31 shows its designator – [silk] designators is top"	the part was placed again after silk apply (a swap, a footprint rebuilt) and came back with its designator shown	edakit silk apply (it hides the designators of [silk] hide), then the gate again; wanted there: accept GEO.silk on the part
GEO.silk: "TOP (visible): text 'TEST' at (15.0, 3.0) mm is neither the board label nor a [[silk.texts]] entry of this side"	a text placed by hand, or an old board label silk apply did not make	delete it, or put it into [[silk.texts]] with side = the visible side and run silk apply
SYNC.plan: "D1, R2: no row in hardware/boards/main.toml [place] (2 of 17 parts)"	the auto-layout placed them before edakit wrote its positions back, or parts came into the graph since	edakit pcb apply, then edakit pcb autolayout: it writes their rows (auto = true); a board already routed: edakit pcb takeover --write once, before any pcb dump – fixed rows where the parts stand (the placement plan, 7.4)
uv run … exits 120 without output inside Claude Code	uv from snap cannot write to the file Claude Code hands it	… 2>&1 \| cat
a wait loop never ends	pgrep -f matches its own shell	wait for an end line or the PID (long runs, 11.3)
EasyEDA crashed during a long run	V8 out of memory	restart, find the state, rerun the whole step; second crash: smaller blocks (start skill, section 4)
JLCPCB BOM tool: part missing	not in the assembly catalogue / no stock	gate check PARTS.stock asks the catalogue before the upload; at another maker ORDER.parts holds its matching to the release
edakit cart prepare stops	the files are not the release's, the circuit, layout or order settings changed since the run, M-6 is not signed for it, the run did not check the maker or has findings for it, [cart] ship_to or shipping missing	its message names which; a new gate run, or the key set (ordering at the manufacturer, 8.4)
edakit cart check exits 2	a check of ORDER.form to ORDER.review failed – a field, a part, a file or the finish not as the release says	check.md names the values; nothing goes into the cart until the page or the release is right
edakit cart check exits 3	ORDER.form to ORDER.finish passed, the regulatory review of the order is missing	the agent regulatory-reviewer "At the order", its result in regulatory.md (skill cart, step 8)
The skill cart stops at a field	the form shows a field, label or value its profile does not have, or asks a consent, a CAPTCHA or a login	you give the consent or sign in; a changed form goes into the profile, then edakit cart prepare again
Eurocircuits: no 1.6 mm under "Board thickness"	Eurocircuits makes 1.55 mm	thickness_mm = 1.55 in the board file; FILES.order finds 1.6 mm before the cart
AISLER assigns no parts	its BOM tab matches by MPN, and the ODB++ carries none	the KiCad tool chain writes MPN and Manufacturer into the footprints; SYNC.odb names a component without its MPN