Troubleshooting Guide

Common issues and solutions for MAG Claude Plugins.

🚨 Common Issues

Plugin Not Loading

Symptom

Plugin doesn't appear in /plugin list or isn't available in Claude Code.

Solutions

1. Check Settings Format

Your .claude/settings.json must use object format, not array format:

// ✅ CORRECT - Object format (required)
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true,
    "code-analysis@mag-claude-plugins": true
  }
}

// ❌ INCORRECT - Array format (will cause validation error)
{
  "enabledPlugins": [
    "frontend@mag-claude-plugins",
    "code-analysis@mag-claude-plugins"
  ]
}

2. Verify Marketplace is Added

# List installed marketplaces
/plugin marketplace list

# If marketplace not listed, add it
/plugin marketplace add MadAppGang/claude-code

3. Check Settings File Location

# Settings must be in project root
ls -la .claude/settings.json

# If missing, create it
mkdir -p .claude
cat > .claude/settings.json <<EOF
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}
EOF

4. Reload Plugin

/plugin reload frontend@mag-claude-plugins

5. Restart Claude Code

Complete restart may be needed for some changes.

Marketplace Not Found

Symptom

Error: "Marketplace 'mag-claude-plugins' not found"

Solutions

1. Add Marketplace

/plugin marketplace add MadAppGang/claude-code

2. Verify Marketplace Added

/plugin marketplace list

3. Update Marketplace Metadata

/plugin marketplace update mag-claude-plugins

4. Re-add if Needed

# Remove and re-add
/plugin marketplace remove mag-claude-plugins
/plugin marketplace add MadAppGang/claude-code

5. Check Internet Connection

# Test GitHub access
ping github.com
curl -I https://github.com/MadAppGang/claude-code

Environment Variables Missing

Symptom

Plugin loads but features don't work (e.g., Figma import fails, API calls fail)

Solutions

1. Check Required Variables

See plugin documentation for required variables:

Frontend Plugin Dependencies
Check plugin's README.md

2. Set Environment Variables

In shell profile (~/.zshrc or ~/.bashrc):

export FIGMA_ACCESS_TOKEN="your-token-here"
export APIDOG_API_TOKEN="your-token-here"

In project .env file:

# Create .env in project root
cat > .env <<EOF
FIGMA_ACCESS_TOKEN=your-token-here
APIDOG_API_TOKEN=your-token-here
EOF

3. Reload Shell

source ~/.zshrc
# or
source ~/.bashrc

4. Verify Variables Are Set

echo $FIGMA_ACCESS_TOKEN
echo $APIDOG_API_TOKEN

5. Use Configuration Command

Some plugins have setup commands:

/configure-mcp

This will guide you through setting up required variables.

Wrong Plugin Version

Symptom

Features missing or plugin behaves differently than expected

Solutions

1. Check Installed Version

/plugin list

Look for version number next to plugin name.

2. Check Latest Version

/plugin marketplace update mag-claude-plugins
/plugin list

3. Update Plugin

# Method 1: Marketplace update (automatic)
/plugin marketplace update mag-claude-plugins

# Method 2: Reinstall plugin
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

4. Install Specific Version

/plugin install frontend@mag-claude-plugins@2.3.0

Settings Validation Error

Symptom

Error about invalid settings format or validation failure

Common Causes & Fixes

1. Wrong enabledPlugins Format

// ❌ WRONG - Array
"enabledPlugins": ["frontend@mag-claude-plugins"]

// ✅ CORRECT - Object
"enabledPlugins": {
  "frontend@mag-claude-plugins": true
}

2. Invalid JSON Syntax

// ❌ WRONG - Trailing comma
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true,
  }
}

// ✅ CORRECT - No trailing comma
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}

3. Missing Quotes

// ❌ WRONG - Unquoted value
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": yes
  }
}

// ✅ CORRECT - Quoted boolean
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}

Validate JSON:

# Check if JSON is valid
cat .claude/settings.json | python3 -m json.tool

MCP Server Not Working

Symptom

Features that require MCP servers don't work (Figma import, browser testing, etc.)

Solutions

1. Check MCP Configuration

Verify MCP servers are configured in Claude Code settings.

2. Verify Environment Variables

# Check required variables
echo $FIGMA_ACCESS_TOKEN
echo $CHROME_EXECUTABLE_PATH

3. Use Configuration Command

/configure-mcp

This checks existing configuration and helps set up missing pieces.

4. Test MCP Server Manually

# Test Figma MCP server
npx @modelcontextprotocol/server-figma --help

# Test Chrome DevTools server
npx @automatalabs/mcp-server-chrome --help

5. Check Node.js Version

node --version
# Should be 18.x or higher

6. Reinstall MCP Servers

# Clear npm cache
npm cache clean --force

# Reinstall (MCP servers are installed on-demand)
# Just run the feature that uses the server

Agent/Command Not Found

Symptom

Trying to use an agent or command results in "not found" error

Solutions

1. Verify Plugin is Enabled

/plugin list

Enabled plugins show with a checkmark or indicator.

2. Check Plugin Manifest

# View plugin configuration
cat .claude-plugin/marketplace.json

# Or for installed plugin
cat ~/.config/claude-code/plugins/frontend@mag-claude-plugins/plugin.json

Verify the agent/command is listed in agents or commands arrays.

3. Reload Plugin

/plugin reload frontend@mag-claude-plugins

4. Reinstall Plugin

/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

5. Check Spelling

Agent and command names are case-sensitive and must match exactly.

Performance Issues

Symptom

Claude Code is slow or plugins are taking too long to respond

Solutions

1. Check System Resources

# Check CPU and memory usage
top
# or
htop

2. Reduce Concurrent Operations

Don't run multiple agents simultaneously
Wait for one operation to complete before starting another

3. Clear Plugin Cache

# Remove and reinstall plugins
/plugin remove frontend@mag-claude-plugins
/plugin install frontend@mag-claude-plugins

4. Check Network Speed

Some plugins make API calls:

# Test network speed
speedtest-cli
# or visit https://fast.com

5. Update to Latest Version

/plugin marketplace update mag-claude-plugins

Permission Errors

Symptom

Errors about file permissions or access denied

Solutions

1. Check File Permissions

# Check settings file
ls -la .claude/settings.json

# Should be readable/writable by your user
# If not, fix permissions:
chmod 644 .claude/settings.json

2. Check Directory Permissions

# Check plugin directory
ls -la ~/.config/claude-code/plugins/

# Fix if needed
chmod -R 755 ~/.config/claude-code/

3. Run Without Sudo

Never run Claude Code with sudo. This can cause permission issues.

🔍 Debugging Steps

Systematic Debugging

When encountering an issue, follow these steps in order:

1. Check Plugin Status

/plugin list

2. Verify Settings

cat .claude/settings.json

3. Check Marketplace

/plugin marketplace list

4. Verify Environment

echo $FIGMA_ACCESS_TOKEN
echo $APIDOG_API_TOKEN
node --version

5. Review Logs Check Claude Code logs for error messages (location varies by OS)

6. Test in Isolation

Disable other plugins
Test with minimal configuration
Try in a fresh project

7. Reinstall

/plugin remove plugin-name@marketplace-name
/plugin install plugin-name@marketplace-name

📝 Getting Help

Before Asking for Help

Gather this information:

Plugin version
```
/plugin list
```
Claude Code version Check in Claude Code settings/about
OS and version
```
uname -a
```
Settings file
```
cat .claude/settings.json
```
Error message Copy the exact error message
Steps to reproduce List steps that cause the issue

Where to Get Help

GitHub Issues (Recommended)

Report a bug
Ask a question
Search existing issues first

Email Support

i@madappgang.com
Include all information listed above

Documentation

💡 Prevention Tips

Avoid Common Mistakes

✅ Always use object format for enabledPlugins
✅ Keep plugins updated regularly
✅ Set environment variables before using features
✅ Test changes in a safe environment first
✅ Read plugin documentation before using new features

Best Practices

Commit .claude/settings.json to version control
Document required env vars in project README
Keep marketplace updated monthly
Test plugins after Claude Code updates
Backup settings before major changes

🆘 Emergency Recovery

Plugin Completely Broken

# 1. Remove all plugins
/plugin list
# Note which plugins are installed

# 2. Remove broken plugin
/plugin remove frontend@mag-claude-plugins

# 3. Remove marketplace
/plugin marketplace remove mag-claude-plugins

# 4. Re-add marketplace
/plugin marketplace add MadAppGang/claude-code

# 5. Reinstall plugins
/plugin install frontend@mag-claude-plugins

# 6. Verify
/plugin list

Settings File Corrupted

# 1. Backup current settings
cp .claude/settings.json .claude/settings.json.backup

# 2. Create fresh settings
cat > .claude/settings.json <<EOF
{
  "enabledPlugins": {
    "frontend@mag-claude-plugins": true
  }
}
EOF

# 3. Restart Claude Code

# 4. Verify
cat .claude/settings.json

Complete Reset

Warning: This removes all plugin configuration.

# 1. Remove all marketplaces
/plugin marketplace list
# Remove each one

# 2. Remove settings
rm -rf .claude/settings.json

# 3. Start fresh
# Follow Quick Start guide in README

📖 Related Documentation

Quick Start - Installation guide
Advanced Usage - Advanced configuration
Development Guide - Plugin development
Frontend Plugin Guide - Complete user guide

Still stuck? Open an issue or email i@madappgang.com

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

🚨 Common Issues

Plugin Not Loading

Symptom

Solutions

Marketplace Not Found

Symptom

Solutions

Environment Variables Missing

Symptom

Solutions

Wrong Plugin Version

Symptom

Solutions

Settings Validation Error

Symptom

Common Causes & Fixes

MCP Server Not Working

Symptom

Solutions

Agent/Command Not Found

Symptom

Solutions

Performance Issues

Symptom

Solutions

Permission Errors

Symptom

Solutions

🔍 Debugging Steps

Systematic Debugging

📝 Getting Help

Before Asking for Help

Where to Get Help

💡 Prevention Tips

Avoid Common Mistakes

Best Practices

🆘 Emergency Recovery

Plugin Completely Broken

Settings File Corrupted

Complete Reset

📖 Related Documentation