Troubleshooting

Solutions for common issues with Claude Code, plugins, and MCP servers.

System Check

For any unexplained issue, run claude doctor first — it surfaces config, plugin, and MCP server status in one report.

Start with these diagnostics:

# Run system health check (config, plugins, MCP status)
claude doctor

# List all installed servers
claude mcp list

# Check Node.js and npm
node --version && npm --version

# Verify UV installation for Python servers
uv --version

Plugin Issues

Plugin not appearing in /plugin list

• Ensure marketplace is added: /plugin marketplace add agronod/claude-plugins
• Verify git authentication: ssh -T git@github.com (should succeed)
• Check Claude Code logs: settings → logs → debug level

Command not available after plugin install

• Restart Claude Code completely (not just refresh)
• Verify plugin installed: /plugin → check status
• Review plugin's SKILL.md for command names and activation conditions

Plugin activation fails or times out

• Check network connectivity to GitHub
• Review recent commits in the claude-plugins repo — a breaking change may have shipped
• Enable debug logging: settings → logs → debug level, then retry

MCP Server Issues

Server won't start (stdio error)

• Verify Node.js or Python is installed and accessible
• Check command syntax in .claude/config.json:

  # Test locally
  npx -y mcp-server-git --version

• Ensure paths are absolute, not relative

Server starts but tools don't appear

• Restart Claude Code
• Run claude mcp list to confirm server is loaded
• Check for errors in Claude Code logs (debug level)

Authentication fails for remote servers

• Verify credentials are correct and not expired
• For OAuth servers (Atlassian, etc.), revoke and re-authenticate: remove server and re-add
• Check environment variables are set correctly in config

Server crashes during tool execution

• Enable debug logging to see the actual error
• Try adding the server manually: claude mcp add <name> <command> [args...], then test a simple tool
• Review the server's documentation for known limitations

Installation Issues

Permission denied when installing Node servers

• Check npm permissions: npm list -g (verify npm install location)
• Reinstall Node.js or npm if permissions are corrupted
• Use sudo only as a last resort — it often creates more issues

UV/Python server won't start

• Verify UV is installed: uv --version
• Test Python directly: python3 --version
• Install missing dependencies: uv pip install <package>

Configuration Issues

.mcp.json not being recognized

• Ensure file is valid JSON: jq . < .mcp.json
• Place in the right location:
  • Local: .mcp.json (project root, private)
  • Project: .mcp.json (shared, version controlled)
  • User: ~/.claude/config.json (global)
• Restart Claude Code after adding servers

Environment variables not being passed to servers

• Verify syntax in config:

  "env": {
    "VAR_NAME": "value"
  }

• Restart Claude Code after changes
• Check with claude mcp list to confirm var is loaded

Diagnostics for Bug Reports

When reporting an issue, gather:

# Log level: set in settings.json, then reproduce the issue
cat ~/.claude/logs/debug.log | tail -50

# Server configuration
cat .mcp.json | jq .

# System info
node --version && npm --version && uv --version

# Server test (replace server-name)
npx -y <server-name> --version

Then open an issue at github.com/agronod/ai-coding-guidelines/issues.

Related

• MCP Installation - Setup guide
• MCP Safety Guidelines - Verify server sources
• Agronod Plugins - Marketplace overview