leo-claude-mktplace/docs/DEBUGGING-CHECKLIST.md

Debugging Checklist for Marketplace Troubleshooting

Purpose: Systematic approach to diagnose and fix plugin loading issues.

Last Updated: 2026-01-28

---

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:

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

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

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 MCP Configuration

Check .mcp.json at marketplace root is correctly configured:

RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace

# Check .mcp.json exists and has valid content
cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'

# Should list: gitea, netbox, data-platform, viz-platform, contract-validator

---

Step 5: Test MCP Server Startup

Manually test if the MCP server can start:

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:

# 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_REPO=owner/repo (e.g., my-org/my-repo)

---

Step 7: Verify Hooks Configuration

Check hooks are valid:

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:

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=== MCP Configuration ==="
[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: 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
Missing .mcp.json	MCP tools not available	Check .mcp.json exists at marketplace root
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)
Gitea issues not closing	Merged to non-default branch	Manually close issues (see below)
MCP changes not taking effect	Session caching	Restart Claude Code session (see below)

Gitea Auto-Close Behavior

Issue: Using Closes #XX or Fixes #XX in commit/PR messages does NOT auto-close issues when merging to development.

Root Cause: Gitea only auto-closes issues when merging to the default branch (typically main or master). Merging to development, staging, or any other branch will NOT trigger auto-close.

Workaround:

1. Use the Gitea MCP tool to manually close issues after merging to development:

   mcp__plugin_projman_gitea__update_issue(issue_number=XX, state="closed")
   

2. Or close issues via the Gitea web UI
3. The auto-close keywords will still work when the changes are eventually merged to main

Recommendation: Include the Closes #XX keywords in commits anyway - they'll work when the final merge to main happens.

MCP Session Restart Requirement

Issue: Changes to MCP servers, hooks, or plugin configuration don't take effect immediately.

Root Cause: Claude Code loads MCP tools and plugin configuration at session start. These are cached in session memory and not reloaded dynamically.

What requires a session restart:

• MCP server code changes (Python files in mcp-servers/)
• Changes to .mcp.json files
• Changes to hooks/hooks.json
• Changes to plugin.json
• Adding new MCP tools or modifying tool signatures

What does NOT require a restart:

• Command/skill markdown files (.md) - these are read on invocation
• Agent markdown files - read when agent is invoked

Correct workflow after plugin changes:

1. Make changes to source files
2. Run ./scripts/verify-hooks.sh to validate
3. Inform user: "Please restart Claude Code for changes to take effect"
4. Do NOT clear cache mid-session - see "Cache Clearing" section

---

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

---

Cache Clearing: When It's Safe vs Destructive

⚠️ CRITICAL: Never clear plugin cache mid-session.

Why Cache Clearing Breaks MCP Tools

When Claude Code starts a session:

1. MCP tools are loaded from the cache directory
2. Tool definitions include absolute paths to the venv (e.g., ~/.claude/plugins/cache/.../venv/)
3. These paths are cached in the session memory
4. Deleting the cache removes the venv, but the session still references the old paths
5. Any MCP tool making HTTP requests fails with TLS certificate errors

When Cache Clearing is SAFE

Scenario	Safe?	Action
Before starting Claude Code	✅ Yes	Clear cache, then start session
Between sessions	✅ Yes	Clear cache after /exit, before next session
During a session	❌ NO	Never - will break MCP tools
After plugin source edits	❌ NO	Restart session instead

Recovery: MCP Tools Broken Mid-Session

If you accidentally cleared cache during a session and MCP tools fail:

Error: Could not find a suitable TLS CA certificate bundle, invalid path:
/home/.../.claude/plugins/cache/.../certifi/cacert.pem

Fix:

1. Exit the current session (/exit or Ctrl+C)
2. Start a new Claude Code session
3. MCP tools will reload from the reinstalled cache

Correct Workflow for Plugin Development

1. Make changes to plugin source files
2. Run ./scripts/verify-hooks.sh (verifies hook types)
3. Tell user: "Please restart Claude Code for changes to take effect"
4. Do NOT clear cache - session restart handles reloading

---

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