claude-code-subagents-orchestrator/docs/TROUBLESHOOTING.md

Claude Code Sub-agents Orchestrator - A powerful MCP server for orchestrating multiple AI sub-agents for complex task execution in Claude Code

# Troubleshooting Guide

## Quick Diagnostics

Before diving into specific issues, run the health check tool:

```bash
claude-orchestrator health-check --verbose
```

This will identify most common problems automatically.

## Common Issues

### Installation Problems

#### Issue: "claude-orchestrator command not found"

**Symptoms:**
- Command not recognized after installation
- "command not found" or "'claude-orchestrator' is not recognized"

**Solutions:**

1. **Check if globally installed:**
   ```bash
   npm list -g claude-code-subagents-orchestrator
   ```

2. **Verify PATH configuration:**
   ```bash
   # Check npm global bin directory
   npm config get prefix
   
   # Add to PATH if missing (add to ~/.bashrc, ~/.zshrc, or equivalent)
   export PATH="$(npm config get prefix)/bin:$PATH"
   ```

3. **Reinstall globally:**
   ```bash
   npm uninstall -g claude-code-subagents-orchestrator
   npm install -g claude-code-subagents-orchestrator
   ```

4. **Use npx as alternative:**
   ```bash
   npx claude-code-subagents-orchestrator --help
   ```

#### Issue: "Permission denied" during installation

**Symptoms:**
- EACCES or EPERM errors during npm install
- Permission denied errors

**Solutions:**

1. **Use npm's built-in permission fix:**
   ```bash
   npm config set prefix ~/.npm-global
   export PATH=~/.npm-global/bin:$PATH
   npm install -g claude-code-subagents-orchestrator
   ```

2. **Fix npm permissions (Linux/macOS):**
   ```bash
   sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
   ```

3. **Use sudo (not recommended but works):**
   ```bash
   sudo npm install -g claude-code-subagents-orchestrator
   ```

4. **Use a Node version manager:**
   ```bash
   # Install nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   npm install -g claude-code-subagents-orchestrator
   ```

#### Issue: "Node.js version incompatible"

**Symptoms:**
- Installation fails with version requirements
- Runtime errors about unsupported features

**Solutions:**

1. **Check Node.js version:**
   ```bash
   node --version
   ```

2. **Update Node.js:**
   - Visit [nodejs.org](https://nodejs.org/) and download latest LTS
   - Or use a version manager:
     ```bash
     nvm install --lts
     nvm use --lts
     ```

3. **Use specific Node version:**
   ```bash
   nvm install 18
   nvm use 18
   npm install -g claude-code-subagents-orchestrator
   ```

### MCP Server Registration Issues

#### Issue: Orchestrator not appearing in Claude Code

**Symptoms:**
- Claude Code doesn't show orchestrator tools
- No MCP server connection established

**Solutions:**

1. **Check Claude Code installation:**
   ```bash
   # Verify Claude Code config directory exists
   # Windows: %APPDATA%\Claude\
   # macOS: ~/Library/Application Support/Claude/
   # Linux: ~/.config/claude/
   ```

2. **Manually register MCP server:**
   ```bash
   claude-orchestrator init --force
   ```

3. **Check configuration file:**
   - Open `claude_desktop_config.json`
   - Verify the orchestrator entry exists:
     ```json
     {
       "mcpServers": {
         "claude-code-subagents-orchestrator": {
           "type": "stdio",
           "command": "node",
           "args": ["/path/to/dist/server.js"]
         }
       }
     }
     ```

4. **Restart Claude Code:**
   - Close Claude Code completely
   - Wait 5 seconds
   - Restart Claude Code

5. **Check server path:**
   ```bash
   # Find where the server is installed
   npm list -g claude-code-subagents-orchestrator
   
   # Update config with correct path
   claude-orchestrator init --force
   ```

#### Issue: "MCP server failed to start"

**Symptoms:**
- Claude Code shows MCP connection errors
- Server startup failures in logs

**Solutions:**

1. **Test server manually:**
   ```bash
   node $(npm root -g)/claude-code-subagents-orchestrator/dist/server.js
   ```

2. **Check server dependencies:**
   ```bash
   claude-orchestrator health-check --verbose
   ```

3. **Rebuild the package:**
   ```bash
   npm uninstall -g claude-code-subagents-orchestrator
   npm install -g claude-code-subagents-orchestrator
   ```

4. **Check Node.js path in config:**
   ```bash
   # Find Node.js path
   which node
   
   # Update MCP config to use full path
   ```

### Runtime Issues

#### Issue: "Agent not found" errors

**Symptoms:**
- Specific agents fail to load
- "Agent specification not found" messages

**Solutions:**

1. **Refresh agent specifications:**
   ```bash
   claude-orchestrator update-agents
   ```

2. **Check agent repository access:**
   ```bash
   # Test network connectivity
   curl -I https://github.com/anthropic/claude-agents
   ```

3. **Clear cache and reload:**
   ```bash
   claude-orchestrator clear-cache
   claude-orchestrator bootstrap --force
   ```

4. **Check agent specification format:**
   - Verify agent YAML/JSON files are valid
   - Run validation: `claude-orchestrator validate-agents`

#### Issue: Slow performance or timeouts

**Symptoms:**
- Long response times
- Timeout errors
- High CPU/memory usage

**Solutions:**

1. **Check system resources:**
   ```bash
   # Monitor resources while running
   top -p $(pgrep -f claude-orchestrator)
   ```

2. **Optimize configuration:**
   ```bash
   # Reduce concurrent agents
   claude-orchestrator config set max-concurrent-agents 3
   
   # Enable caching
   claude-orchestrator config set enable-caching true
   ```

3. **Clear cache and logs:**
   ```bash
   claude-orchestrator clear-cache
   claude-orchestrator clear-logs
   ```

4. **Update to latest version:**
   ```bash
   npm update -g claude-code-subagents-orchestrator
   ```

### Platform-Specific Issues

#### Windows Issues

**Issue: PowerShell execution policy errors**

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**Issue: Path separators in config**

Ensure Windows paths use proper format:
```json
"args": ["C:\\Users\\username\\AppData\\Roaming\\npm\\node_modules\\claude-code-subagents-orchestrator\\dist\\server.js"]
```

**Issue: Windows Defender blocking execution**

Add exceptions for:
- Node.js executable
- npm global directory
- Orchestrator installation directory

#### macOS Issues

**Issue: Gatekeeper blocking execution**

```bash
# Remove quarantine attribute
xattr -d com.apple.quarantine /usr/local/bin/claude-orchestrator
```

**Issue: SIP restrictions**

Use user-local npm installation:
```bash
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

#### Linux Issues

**Issue: Missing dependencies**

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
```

**Issue: AppArmor/SELinux restrictions**

```bash
# Check for denials
sudo ausearch -m avc -ts recent

# Add policy if needed
sudo setsebool -P httpd_can_network_connect 1
```

### Docker Issues

#### Issue: Container won't start

**Solutions:**

1. **Check logs:**
   ```bash
   docker logs claude-orchestrator
   ```

2. **Check resource limits:**
   ```bash
   docker stats claude-orchestrator
   ```

3. **Rebuild image:**
   ```bash
   docker-compose build --no-cache
   docker-compose up -d
   ```

#### Issue: Port conflicts

```bash
# Find what's using the port
lsof -i :3000

# Use different port
docker run -p 3001:3000 claude-orchestrator
```

### Network Issues

#### Issue: Cannot reach external services

**Solutions:**

1. **Check connectivity:**
   ```bash
   # Test basic connectivity
   ping google.com
   
   # Test HTTPS
   curl -I https://github.com
   ```

2. **Check proxy settings:**
   ```bash
   # Set npm proxy
   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   ```

3. **Check firewall:**
   ```bash
   # Test if port is open
   telnet github.com 443
   ```

4. **Use alternative registry:**
   ```bash
   npm config set registry https://registry.npmjs.org/
   ```

## Advanced Diagnostics

### Verbose Logging

Enable detailed logging for troubleshooting:

```bash
# Set debug environment
export DEBUG=claude-orchestrator:*
export LOG_LEVEL=debug

# Run with verbose output
claude-orchestrator --verbose command
```

### Log File Locations

- **Global logs**: `~/.claude-orchestrator/logs/`
- **System logs**: `/var/log/claude-orchestrator/` (Linux)
- **Docker logs**: `docker logs <container_name>`

### Configuration Validation

```bash
# Validate configuration
claude-orchestrator validate-config

# Reset to defaults
claude-orchestrator reset-config

# Show current config
claude-orchestrator show-config
```

### Manual Testing

Test components individually:

```bash
# Test MCP server directly
node path/to/server.js

# Test agent loading
claude-orchestrator test-agent agent-name

# Test network connectivity
claude-orchestrator test-network
```

## Getting Help

### Self-Service Options

1. **Run health check:** `claude-orchestrator health-check --verbose`
2. **Check logs:** `claude-orchestrator logs --tail 50`
3. **Validate setup:** `claude-orchestrator validate`
4. **Reset configuration:** `claude-orchestrator reset --confirm`

### Collecting Debug Information

Before reporting issues, collect this information:

```bash
# System information
claude-orchestrator health-check --json > debug-info.json

# Version information
claude-orchestrator --version
node --version
npm --version

# Configuration
claude-orchestrator show-config

# Recent logs
claude-orchestrator logs --tail 100 > logs.txt
```

### Reporting Issues

When reporting bugs, include:

1. Output of `claude-orchestrator health-check --verbose`
2. Operating system and version
3. Node.js and npm versions
4. Steps to reproduce the issue
5. Expected vs actual behavior
6. Relevant log entries

**GitHub Issues:** https://github.com/anthropic/claude-code-subagents-orchestrator/issues

### Community Support

- **Documentation:** https://github.com/anthropic/claude-code-subagents-orchestrator/docs
- **FAQ:** [FAQ.md](FAQ.md)
- **Discussions:** GitHub Discussions tab

## Prevention

### Regular Maintenance

```bash
# Update regularly
npm update -g claude-code-subagents-orchestrator

# Clean cache monthly
claude-orchestrator clear-cache

# Validate configuration
claude-orchestrator validate-config

# Check for issues
claude-orchestrator health-check
```

### Best Practices

1. **Keep Node.js updated** to the latest LTS version
2. **Use global installation** for command-line access
3. **Regular health checks** to catch issues early
4. **Monitor logs** for warnings and errors
5. **Backup configuration** before major changes