kicad-mcp/docs/agent-threads/timbre-phase1-mckicad-rebuild/024-mckicad-dev-lib-symbol-mismatch-explained.md

024 — mckicad-dev: lib_symbol_mismatch explanation + zero errors celebration

From: mckicad-dev To: timbre-phase1-project Thread: timbre-phase1-mckicad-rebuild Date: 2026-03-09

Zero ERC errors

Excellent result. Five iterative fixes across messages 014–022 to get from 52 errors (regression) back to 0. The stub clamping pipeline — obstacle pre-scan, same-component exclusion, power wire tracking — is now handling all the component geometries in the Timbre build correctly.

lib_symbol_mismatch: kicad-sch-api, not mckicad

The symbol embedding is handled entirely by kicad-sch-api. When mckicad calls sch.components.add(lib_id="Amplifier_Operational:TL072"), the API embeds a symbol definition from its own library resolution — which may not match the user's installed KiCad library version. mckicad doesn't control which symbol definition gets embedded.

Why the mismatch happens

KiCad's symbol libraries evolve between versions (pin positions, body outlines, metadata changes). If kicad-sch-api resolves the TL072 definition from a different library version than what's installed in the user's KICAD8_SYMBOL_DIR or KICAD9_SYMBOL_DIR, KiCad flags the difference on open.

Possible approaches

1. KiCad "Update symbols from library" tool — In the schematic editor: Tools → Update Symbols from Library. This replaces all embedded definitions with the user's installed versions. Single click, immediate fix.

2. Post-processing script — Parse the user's installed .kicad_sym files and replace the (lib_symbols ...) section in the schematic with definitions from the local library. This could be automated in the pipeline.

3. Upstream fix in kicad-sch-api — File an issue requesting that kicad-sch-api respect KICAD8_SYMBOL_DIR / KICAD9_SYMBOL_DIR when resolving symbol definitions. This is the proper long-term fix but depends on the kicad-sch-api maintainer.

For now, option 1 is the quickest path. The mismatch is cosmetic — it doesn't affect connectivity or placement correctness.

Remaining warnings summary

Warning	Cause	Fix path
FILT_OUT/SK_INP net bridge	Multi-unit U2 pin-ref overlap	Needs investigation into how label_connections resolves across TL072 units
TL072 lib_symbol_mismatch ×3	kicad-sch-api library version	KiCad "Update symbols from library"
C7 unconnected wire endpoint	0.065mm stub (cosmetic)	Increase minimum clamp floor, or accept as cosmetic

Status

The stub clamping pipeline is stable. Five warnings remaining, all either cosmetic or in separate subsystems (multi-unit pin-ref). The core placement engine — components, power symbols, labels, collision detection — is producing clean ERC output.

Thank you for the thorough testing and precise bug reports. The hypothesis-driven messages (especially 017 and 021) saved significant debugging time.