f047a4e4d1
Major documentation update bringing all docs current with the 122-tool, 16-category state of the project (previously frozen at v2.1.0-alpha/59 tools). New documentation (9 files): - FREEROUTING_GUIDE.md - autorouter setup, Docker/Podman, all 4 tools - SCHEMATIC_TOOLS_REFERENCE.md - all 27 schematic tools with parameters - ROUTING_TOOLS_REFERENCE.md - all 13 routing tools with examples - FOOTPRINT_SYMBOL_CREATOR_GUIDE.md - 8 creator tools with examples - SVG_IMPORT_GUIDE.md - SVG logo import tool - DATASHEET_TOOLS_GUIDE.md - datasheet enrichment tools - PCB_DESIGN_WORKFLOW.md - end-to-end design guide - ARCHITECTURE.md - system architecture for contributors - INDEX.md - documentation table of contents Updated documentation (12 files): - README.md - tool count 64->122, feature list, contributor credits - TOOL_INVENTORY.md - complete rebuild with all 122 tools - STATUS_SUMMARY.md - updated to v2.2.3 feature matrix - ROADMAP.md - marked completed milestones, added v2.3+ vision - KNOWN_ISSUES.md - removed resolved issues, added v2.2.x fixes - CLIENT_CONFIGURATION.md - added KICAD_MCP_DEV, FREEROUTING_JAR env vars - LIBRARY_INTEGRATION.md - added symbol and project-local library support - ROUTER_ARCHITECTURE.md, ROUTER_QUICK_START.md - updated tool counts - IPC_BACKEND_STATUS.md - updated dates - JLCPCB_USAGE_GUIDE.md - added cross-reference note - CONTRIBUTING.md - added ARCHITECTURE.md reference, updated tool count Archived 10 completed planning docs to docs/archive/. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
# 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
|
|
```bash
|
|
# 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](IPC_BACKEND_STATUS.md) for IPC details
|
|
- Check logs: `~/.kicad-mcp/logs/kicad_interface.log`
|
|
- Open an issue on GitHub
|