# 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.