lmiranda
2d51df7a42
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.9 KiB
Log Analysis Skill
Common MCP server error patterns, their root causes, and fixes.
Error Pattern: ImportError
ImportError: No module named 'pynetbox'
Root Cause: Missing Python package in the virtual environment.
Fix:
cd <server_cwd> && .venv/bin/pip install -r requirements.txt
Prevention: Always run pip install -r requirements.txt after creating or updating a venv.
Error Pattern: ConnectionRefused
ConnectionRefusedError: [Errno 111] Connection refused
Root Cause: The external service the MCP server connects to is not running or not reachable.
Checks:
- Is the target service running? (e.g., Gitea, NetBox)
- Is the URL correct in the env file?
- Is there a firewall or VPN issue?
Fix: Verify the service URL in ~/.config/claude/<server>.env and confirm the service is accessible.
Error Pattern: JSONDecodeError
json.decoder.JSONDecodeError: Expecting value: line 1 column 1
Root Cause: The server received non-JSON response from the external API. Usually means:
- API returned HTML error page (wrong URL)
- API returned empty response (auth failed silently)
- Proxy intercepted the request
Fix: Check the API URL ends with the correct path (e.g., /api/v1 for Gitea, /api for NetBox).
Error Pattern: TimeoutError
TimeoutError: timed out
httpx.ReadTimeout:
Root Cause: Server startup took too long or external API is slow.
Checks:
- Network latency to the external service
- Server doing heavy initialization (loading all tools)
- Large response from API
Fix: Increase timeout in server config or reduce initial tool registration.
Error Pattern: PermissionError
PermissionError: [Errno 13] Permission denied: '/path/to/file'
Root Cause: Server process cannot read/write required files.
Fix: Check file ownership and permissions. Common locations:
~/.config/claude/*.env(should be readable by user)- Server's
.venv/directory - Log files
Error Pattern: FileNotFoundError (Venv)
FileNotFoundError: [Errno 2] No such file or directory: '.venv/bin/python'
Root Cause: Virtual environment does not exist or was deleted.
Fix: Create the venv:
cd <server_cwd> && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
Error Pattern: SSL Certificate Error
ssl.SSLCertVerificationError: certificate verify failed
Root Cause: Self-signed certificate on the target service.
Fix: Set VERIFY_SSL=false in the env file (not recommended for production).
Log Parsing Tips
- Python tracebacks - Read from bottom up. The last line is the actual error.
- JSON-RPC errors - Look for
"error"key in JSON responses. - Startup failures - First few lines after server spawn reveal initialization issues.
- Repeated errors - Same error in a loop means the server is retrying and failing.