# Debugging Checklist for Marketplace Troubleshooting **Purpose:** Systematic approach to diagnose and fix plugin loading issues. Last Updated: 2026-01-22 --- ## Step 1: Identify the Loading Path Claude Code loads plugins from different locations depending on context: | Location | Path | When Used | |----------|------|-----------| | **Source** | `~/claude-plugins-work/` | When developing in this directory | | **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | After marketplace install | | **Cache** | `~/.claude/` | Plugin metadata, settings | **Determine which path Claude is using:** ```bash # Check if installed marketplace exists ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/ # Check Claude's current plugin loading cat ~/.claude/settings.local.json | grep -A5 "mcpServers" ``` **Key insight:** If you're editing source but Claude uses installed, your changes won't take effect. --- ## Step 2: Verify Files Exist at Runtime Location Check the files Claude will actually load: ```bash # For installed marketplace RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace # Check MCP server exists ls -la $RUNTIME/mcp-servers/gitea/ ls -la $RUNTIME/mcp-servers/netbox/ # Check plugin manifests ls -la $RUNTIME/plugins/projman/.claude-plugin/plugin.json ls -la $RUNTIME/plugins/pr-review/.claude-plugin/plugin.json # Check .mcp.json files cat $RUNTIME/plugins/projman/.mcp.json ``` --- ## Step 3: Verify Virtual Environments Exist **This is the most common failure point after installation.** MCP servers require Python venvs to exist at the INSTALLED location: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace # Check venvs exist ls -la $RUNTIME/mcp-servers/gitea/.venv/bin/python ls -la $RUNTIME/mcp-servers/netbox/.venv/bin/python # If missing, create them: cd $RUNTIME && ./scripts/setup.sh ``` **Common error:** "X MCP servers failed to start" = venvs don't exist in installed path. --- ## Step 4: Verify Symlink Resolution Plugins use symlinks to shared MCP servers. Verify they resolve correctly: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace # Check symlinks exist and resolve readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox # Should resolve to: # $RUNTIME/mcp-servers/gitea # $RUNTIME/mcp-servers/netbox ``` **If broken:** Symlinks are relative. If directory structure differs, they'll break. --- ## Step 5: Test MCP Server Startup Manually test if the MCP server can start: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace # Test Gitea MCP cd $RUNTIME/mcp-servers/gitea PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')" # Test NetBox MCP cd $RUNTIME/mcp-servers/netbox PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')" ``` **If import fails:** Check requirements.txt installed, check Python version compatibility. --- ## Step 6: Verify Configuration Files Check environment variables are set: ```bash # System-level credentials (should exist) cat ~/.config/claude/gitea.env # Should contain: GITEA_API_URL, GITEA_API_TOKEN cat ~/.config/claude/netbox.env # Should contain: NETBOX_API_URL, NETBOX_API_TOKEN # Project-level config (in target project) cat /path/to/project/.env # Should contain: GITEA_ORG, GITEA_REPO ``` --- ## Step 7: Verify Hooks Configuration Check hooks are valid: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace # List all hooks.json files find $RUNTIME/plugins -name "hooks.json" -exec echo "=== {} ===" \; -exec cat {} \; # Verify hook events are valid # Valid: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, # Notification, Stop, SubagentStop, PreCompact # INVALID: task-completed, file-changed, git-commit-msg-needed ``` --- ## Quick Diagnostic Commands Run these to quickly identify issues: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace echo "=== Installation Status ===" [ -d "$RUNTIME" ] && echo "Installed: YES" || echo "Installed: NO" echo -e "\n=== Virtual Environments ===" [ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING" [ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING" echo -e "\n=== Symlinks ===" [ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING" [ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING" [ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING" echo -e "\n=== Config Files ===" [ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING" [ -f ~/.config/claude/netbox.env ] && echo "netbox.env: OK" || echo "netbox.env: MISSING" ``` --- ## Common Issues and Fixes | Issue | Symptom | Fix | |-------|---------|-----| | Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` | | Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks | | Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes | | Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials | | Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) | --- ## After Fixing Issues 1. **Restart Claude Code** - Plugins are loaded at startup 2. **Verify fix works** - Run a simple command that uses the MCP 3. **Document the issue** - If it's a new failure mode, add to this checklist --- ## Automated Diagnostics Use these commands for automated checking: - `/debug-report` - Run full diagnostics, create issue if problems found - `/debug-review` - Investigate existing diagnostic issues and propose fixes --- ## Related Documentation - `CLAUDE.md` - Installation Paths and Troubleshooting sections - `docs/CONFIGURATION.md` - Setup and configuration guide - `docs/UPDATING.md` - Update procedures