kicad-mcp-server/docs/KNOWN_ISSUES.md

Known Issues & Workarounds

Last Updated: 2026-03-21 Version: 2.2.3

This document tracks known issues and provides workarounds where available.

---

Current Issues

1. get_board_info KiCAD 9.0 API Issue

Status: KNOWN - Non-critical

Symptoms:

AttributeError: 'BOARD' object has no attribute 'LT_USER'

Root Cause: KiCAD 9.0 changed layer enumeration constants

Workaround: Use get_project_info instead for basic project details

Impact: Low - informational command only

---

2. Zone Filling via SWIG Causes Segfault

Status: KNOWN - Workaround available

Symptoms:

• Copper pours created but not filled automatically when using SWIG backend
• Calling ZONE_FILLER via SWIG causes segfault

Workaround Options:

1. Use IPC backend (zones fill correctly via IPC)
2. Open the board in KiCAD UI -- zones fill automatically when opened
3. Use refill_zones tool (may still segfault in some configurations)

Impact: Medium - affects copper pour visualization until opened in KiCAD

---

3. UI Manual Reload Required (SWIG Backend)

Status: BY DESIGN

Symptoms:

• MCP makes changes via SWIG backend
• KiCAD does not show changes until file is reloaded

Why: SWIG-based backend modifies files directly and cannot push changes to a running UI

Fix: Use IPC backend for real-time updates (requires KiCAD running with IPC enabled)

Workaround: Click the reload prompt in KiCAD or use File > Revert

---

4. IPC Backend Limitations

Status: EXPERIMENTAL

Known Limitations:

• KiCAD must be running with IPC enabled (Preferences > Plugins > Enable IPC API Server)
• Some commands fall back to SWIG (e.g., delete_trace)
• Footprint loading uses hybrid approach (SWIG for library, IPC for placement)

Workaround: The server automatically falls back to SWIG backend when IPC is unavailable

---

5. package.json Version Mismatch

Status: KNOWN - Non-critical

Symptoms: package.json shows version 2.1.0-alpha while CHANGELOG documents version 2.2.3

Impact: Cosmetic only. CHANGELOG.md is the authoritative version reference.

---

Recently Fixed (v2.2.0 - v2.2.3)

B.Cu Footprint Routing (Fixed v2.2.3)

• route_pad_to_pad now correctly detects B.Cu footprints and inserts vias
• KiCAD 9 SWIG pad.GetLayerName() always returned F.Cu for flipped footprints -- fixed using footprint.GetLayer()

B.Cu Placement Hang (Fixed v2.2.3)

• Placing footprints on B.Cu no longer causes ~30s freeze
• Fix: call board.Add() before Flip()

Board Outline Rounded Corners (Fixed v2.2.3)

• add_board_outline now correctly applies cornerRadius for rounded_rectangle shape

Project-Local Library Resolution (Fixed v2.2.2)

• add_schematic_component and place_component now search project-local sym-lib-table and fp-lib-table
• Previously only global KiCAD library paths were searched

Template File Corruption (Fixed v2.2.2)

• Removed invalid ;; comment lines from template schematics
• Restored KiCAD 9 format version (20250114) in templates

copy_routing_pattern Empty Results (Fixed v2.2.2)

• Added geometric fallback when pads have no net assignments

Schematic Component Corruption (Fixed v2.2.1)

• add_schematic_component no longer corrupts .kicad_sch files
• Rewritten to use text manipulation instead of sexpdata formatting

SWIG/UUID Comparison Bugs (Fixed v2.2.0)

• Fixed SwigPyObject UUID comparison
• Fixed SWIG iterator invalidation after board.Remove()
• Added board.SetModified() to prevent dangling pointer crashes

---

Reporting New Issues

If you encounter an issue not listed here:

1. Check MCP logs: ~/.kicad-mcp/logs/kicad_interface.log
2. Enable developer mode: Set KICAD_MCP_DEV=1 to capture session logs
3. Check KiCAD version: python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())" (must be 9.0+)
4. Try the operation in KiCAD directly -- is it a KiCAD issue?
5. Open a GitHub issue with:
   • Error message and log excerpt
   • Steps to reproduce
   • KiCAD version and OS
   • MCP session log (from logs/ folder if dev mode is enabled)

---

General Workarounds

Server Will Not Start

# Check Python can import pcbnew
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

# Check paths
python3 python/utils/platform_helper.py

Commands Fail After Server Restart

# Board reference is lost on restart
# Always run open_project after server restart

KiCAD UI Does Not Show Changes (SWIG Mode)

# File > Revert (or click reload prompt)
# Or: Close and reopen file in KiCAD
# Or: Use IPC backend for automatic updates

IPC Not Connecting

# Ensure KiCAD is running
# Enable IPC: Preferences > Plugins > Enable IPC API Server
# Have a board open in PCB editor
# Check socket exists: ls /tmp/kicad/api.sock

---

Need Help?

• Check IPC_BACKEND_STATUS.md for IPC details
• Check logs: ~/.kicad-mcp/logs/kicad_interface.log
• Open an issue on GitHub