unifi-pro-mcp/docs/troubleshooting.md

MCP Server for UniFi Network and Protect systems with multi-device support

# Troubleshooting Guide

Comprehensive troubleshooting guide for UniFi PRO MCP common issues, solutions, and diagnostic procedures.

## 🔍 Table of Contents

- [Quick Diagnostics](#quick-diagnostics)
- [Installation Issues](#installation-issues)
- [Connection Problems](#connection-problems)
- [Authentication Failures](#authentication-failures)
- [Performance Issues](#performance-issues)
- [Claude Desktop Integration](#claude-desktop-integration)
- [Network & Firewall Issues](#network--firewall-issues)
- [SSL/TLS Problems](#ssltls-problems)
- [Configuration Errors](#configuration-errors)
- [Logging & Debugging](#logging--debugging)
- [Common Error Codes](#common-error-codes)
- [Support Resources](#support-resources)

## 🩺 Quick Diagnostics

### Health Check Command

Run the built-in diagnostic tool to quickly identify common issues:

```bash
# Test all components
npx unifi-pro-mcp@latest --test-all

# Test specific component
npx unifi-pro-mcp@latest --test connection
npx unifi-pro-mcp@latest --test auth
npx unifi-pro-mcp@latest --test devices
```

### System Information

Gather system information for troubleshooting:

```bash
# Node.js version
node --version

# NPM version
npm --version

# Package version
npm list unifi-pro-mcp -g

# System information
uname -a

# Network connectivity
ping 8.8.8.8
```

## 📦 Installation Issues

### Issue: `npm install` fails with permission errors

**Symptoms:**
```bash
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
```

**Solutions:**

1. **Use npx (Recommended):**
   ```bash
   npx unifi-pro-mcp@latest
   ```

2. **Fix npm permissions:**
   ```bash
   # macOS/Linux
   sudo chown -R $(whoami) ~/.npm
   sudo chown -R $(whoami) /usr/local/lib/node_modules
   
   # Or configure npm prefix
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
   source ~/.profile
   ```

3. **Use Node Version Manager:**
   ```bash
   # Install nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Install latest Node.js
   nvm install node
   nvm use node
   ```

### Issue: Node.js version incompatibility

**Symptoms:**
```bash
Error: UniFi PRO MCP requires Node.js 18.0.0 or higher
```

**Solutions:**

1. **Update Node.js:**
   ```bash
   # Using nvm
   nvm install 18
   nvm use 18
   
   # Or download from nodejs.org
   # https://nodejs.org/
   ```

2. **Check current version:**
   ```bash
   node --version
   ```

### Issue: Package not found

**Symptoms:**
```bash
npm ERR! 404 Not Found - GET https://registry.npmjs.org/unifi-pro-mcp
```

**Solutions:**

1. **Check package name:**
   ```bash
   npm search unifi-pro-mcp
   ```

2. **Clear npm cache:**
   ```bash
   npm cache clean --force
   ```

3. **Try different registry:**
   ```bash
   npm install unifi-pro-mcp --registry https://registry.npmjs.org/
   ```

## 🔗 Connection Problems

### Issue: Cannot connect to UniFi Controller

**Symptoms:**
```
Error: ECONNREFUSED 192.168.1.1:8443
Connection timeout after 30000ms
```

**Diagnostic Steps:**

1. **Verify controller is running:**
   ```bash
   # Test HTTPS endpoint
   curl -k https://192.168.1.1:8443/inform
   
   # Expected response: Empty response with 200 OK
   ```

2. **Check network connectivity:**
   ```bash
   # Basic connectivity
   ping 192.168.1.1
   
   # Port accessibility
   telnet 192.168.1.1 8443
   
   # Or using nc
   nc -zv 192.168.1.1 8443
   ```

3. **Verify DNS resolution:**
   ```bash
   # If using hostname
   nslookup unifi.local
   
   # Or
   dig unifi.local
   ```

**Solutions:**

1. **Check UniFi Controller status:**
   ```bash
   # On controller host
   sudo systemctl status unifi
   
   # Check logs
   sudo journalctl -u unifi -f
   ```

2. **Verify port configuration:**
   ```bash
   # Check listening ports
   sudo netstat -tlnp | grep :8443
   
   # Or using ss
   sudo ss -tlnp | grep :8443
   ```

3. **Test with different port:**
   ```env
   UNIFI_PORT=8080  # Try HTTP port
   ```

### Issue: Connection drops intermittently

**Symptoms:**
- Successful connections followed by timeouts
- "Connection reset by peer" errors

**Solutions:**

1. **Increase timeout values:**
   ```json
   {
     "controller": {
       "timeout": 60000,
       "keepAlive": true,
       "keepAliveInitialDelay": 300000
     }
   }
   ```

2. **Enable connection pooling:**
   ```json
   {
     "performance": {
       "maxConnections": 5,
       "connectionPool": true
     }
   }
   ```

3. **Check network stability:**
   ```bash
   # Monitor connection quality
   mtr 192.168.1.1
   
   # Check for packet loss
   ping -c 100 192.168.1.1
   ```

## 🔐 Authentication Failures

### Issue: Invalid credentials

**Symptoms:**
```
Error: Authentication failed: Invalid username or password
HTTP 401: Unauthorized
```

**Diagnostic Steps:**

1. **Verify credentials manually:**
   ```bash
   # Test login via browser
   https://192.168.1.1:8443
   
   # Use same credentials as configured
   ```

2. **Check user permissions:**
   - Login to UniFi Controller web interface
   - Go to Settings → Admins
   - Verify user has "Admin" or "Super Admin" role
   - Ensure "API Access" is enabled

**Solutions:**

1. **Reset user password:**
   ```bash
   # In UniFi Controller
   # Settings → Admins → Select User → Change Password
   ```

2. **Create dedicated service account:**
   ```bash
   # Create new admin user for MCP
   # Username: unifi-mcp-service
   # Role: Admin
   # Enable API Access
   ```

3. **Check special characters:**
   ```bash
   # Escape special characters in password
   export UNIFI_PASSWORD='password\!with\$pecial\&chars'
   ```

### Issue: Two-Factor Authentication (2FA)

**Symptoms:**
```
Error: Authentication requires 2FA token
```

**Solutions:**

1. **Disable 2FA for service account:**
   - Recommended for automated access
   - Create separate service account without 2FA

2. **Use application-specific password:**
   - Generate app password in UniFi Controller
   - Use app password instead of main password

### Issue: Account lockout

**Symptoms:**
```
Error: Account temporarily locked due to failed attempts
```

**Solutions:**

1. **Wait for lockout period:**
   - Default: 15 minutes after 5 failed attempts

2. **Reset account lockout:**
   ```bash
   # On UniFi Controller host
   # Stop UniFi service
   sudo systemctl stop unifi
   
   # Reset database (advanced users only)
   # Contact support for assistance
   ```

## ⚡ Performance Issues

### Issue: Slow response times

**Symptoms:**
- API calls take >10 seconds
- Timeouts during data retrieval

**Diagnostic Steps:**

1. **Measure response times:**
   ```bash
   # Time API call
   time npx unifi-pro-mcp@latest --test devices
   
   # Monitor with detailed timing
   curl -k -w "@curl-format.txt" https://192.168.1.1:8443/api/s/default/stat/device
   ```

2. **Check system resources:**
   ```bash
   # Controller system resources
   top
   free -h
   df -h
   
   # Network latency
   ping -c 10 192.168.1.1
   ```

**Solutions:**

1. **Enable caching:**
   ```json
   {
     "cache": {
       "enabled": true,
       "ttl": 300,
       "maxSize": 1000
     }
   }
   ```

2. **Optimize query parameters:**
   ```json
   {
     "performance": {
       "maxConcurrentRequests": 3,
       "requestBatching": true,
       "compressionEnabled": true
     }
   }
   ```

3. **Reduce data scope:**
   ```bash
   # Limit to specific sites
   UNIFI_SITE=specific-site-id
   
   # Filter device types
   # Use API filters where available
   ```

### Issue: Memory leaks

**Symptoms:**
- Increasing memory usage over time
- Process crashes with out-of-memory errors

**Solutions:**

1. **Monitor memory usage:**
   ```bash
   # Check process memory
   ps aux | grep unifi-mcp
   
   # Monitor over time
   watch "ps aux | grep unifi-mcp"
   ```

2. **Enable garbage collection:**
   ```bash
   # Node.js GC options
   export NODE_OPTIONS="--max-old-space-size=512 --gc-interval=100"
   ```

3. **Restart periodically:**
   ```bash
   # Cron job to restart daily
   0 2 * * * systemctl restart unifi-mcp
   ```

## 🖥️ Claude Desktop Integration

### Issue: MCP server not appearing in Claude

**Symptoms:**
- UniFi tools not available in Claude Desktop
- No MCP server connection indicators

**Diagnostic Steps:**

1. **Verify configuration file location:**
   ```bash
   # macOS
   ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   dir %APPDATA%\Claude\claude_desktop_config.json
   
   # Linux
   ls -la ~/.config/Claude/claude_desktop_config.json
   ```

2. **Validate JSON syntax:**
   ```bash
   # Check for syntax errors
   python -m json.tool claude_desktop_config.json
   
   # Or use jq
   jq . claude_desktop_config.json
   ```

**Solutions:**

1. **Fix JSON syntax errors:**
   ```json
   {
     "mcpServers": {
       "unifi-pro": {
         "command": "npx",
         "args": ["unifi-pro-mcp@latest"],
         "env": {
           "UNIFI_HOST": "192.168.1.1",
           "UNIFI_USERNAME": "admin",
           "UNIFI_PASSWORD": "password"
         }
       }
     }
   }
   ```

2. **Check file permissions:**
   ```bash
   chmod 644 claude_desktop_config.json
   ```

3. **Restart Claude Desktop:**
   - Complete application restart required after config changes

### Issue: MCP server starts but tools unavailable

**Symptoms:**
- Server shows as connected
- No UniFi-specific tools available

**Solutions:**

1. **Check server logs:**
   ```bash
   # Enable debug logging
   export DEBUG=unifi-pro-mcp:*
   ```

2. **Test server independently:**
   ```bash
   npx unifi-pro-mcp@latest --test-tools
   ```

3. **Verify environment variables:**
   ```json
   {
     "mcpServers": {
       "unifi-pro": {
         "env": {
           "DEBUG": "unifi-pro-mcp:*",
           "UNIFI_HOST": "192.168.1.1"
         }
       }
     }
   }
   ```

## 🌐 Network & Firewall Issues

### Issue: Firewall blocking connections

**Symptoms:**
```
Error: ETIMEDOUT
Connection timeout after 30000ms
```

**Diagnostic Steps:**

1. **Test connectivity:**
   ```bash
   # Direct connection test
   telnet 192.168.1.1 8443
   
   # Trace route
   traceroute 192.168.1.1
   
   # Check for filtering
   nmap -p 8443 192.168.1.1
   ```

**Solutions:**

1. **Configure firewall rules:**
   ```bash
   # Ubuntu/Debian (ufw)
   sudo ufw allow from CLIENT_IP to any port 8443
   
   # CentOS/RHEL (firewalld)
   sudo firewall-cmd --permanent --add-port=8443/tcp
   sudo firewall-cmd --reload
   
   # iptables
   sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
   ```

2. **Check corporate firewall:**
   - Contact network administrator
   - Request port 8443 access
   - Consider VPN connection

### Issue: Proxy server interference

**Symptoms:**
```
Error: Proxy authentication required
HTTP 407: Proxy Authentication Required
```

**Solutions:**

1. **Configure proxy settings:**
   ```bash
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   export NO_PROXY=192.168.1.1,localhost,127.0.0.1
   ```

2. **Proxy authentication:**
   ```bash
   export HTTPS_PROXY=http://username:password@proxy.company.com:8080
   ```

3. **Bypass proxy for local connections:**
   ```json
   {
     "network": {
       "proxy": {
         "enabled": false,
         "bypassLocal": true
       }
     }
   }
   ```

## 🔒 SSL/TLS Problems

### Issue: Self-signed certificate errors

**Symptoms:**
```
Error: self signed certificate
Error: unable to verify the first certificate
```

**Solutions:**

1. **Disable SSL verification (development only):**
   ```env
   UNIFI_SSL_VERIFY=false
   NODE_TLS_REJECT_UNAUTHORIZED=0
   ```

2. **Add certificate to trust store:**
   ```bash
   # Get certificate
   echo | openssl s_client -connect 192.168.1.1:8443 -servername unifi.local 2>/dev/null | openssl x509 -text > unifi.crt
   
   # Add to system trust store (varies by OS)
   # macOS
   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain unifi.crt
   
   # Ubuntu/Debian
   sudo cp unifi.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates
   ```

3. **Use certificate file:**
   ```env
   UNIFI_SSL_CERT_PATH=/path/to/unifi.crt
   ```

### Issue: Certificate expiration

**Symptoms:**
```
Error: certificate has expired
```

**Solutions:**

1. **Check certificate expiration:**
   ```bash
   echo | openssl s_client -connect 192.168.1.1:8443 2>/dev/null | openssl x509 -dates -noout
   ```

2. **Renew certificate:**
   - Update UniFi Controller certificate
   - Restart UniFi Controller service

## ⚙️ Configuration Errors

### Issue: Invalid configuration format

**Symptoms:**
```
Error: Configuration validation failed
Invalid JSON in config file
```

**Solutions:**

1. **Validate JSON:**
   ```bash
   python -m json.tool config.json
   jq . config.json
   ```

2. **Check required fields:**
   ```json
   {
     "devices": [
       {
         "name": "main-controller",
         "host": "192.168.1.1",
         "username": "admin",
         "password": "password"
       }
     ]
   }
   ```

3. **Use configuration wizard:**
   ```bash
   npx unifi-pro-mcp@latest --setup
   ```

### Issue: Environment variables not loaded

**Symptoms:**
- Configuration values showing as undefined
- Default values being used instead of custom

**Solutions:**

1. **Check environment variable names:**
   ```bash
   env | grep UNIFI
   ```

2. **Load from .env file:**
   ```bash
   # Ensure .env file is in correct location
   ls -la .env
   
   # Check file format
   cat .env
   ```

3. **Explicitly load environment:**
   ```json
   {
     "mcpServers": {
       "unifi-pro": {
         "command": "npx",
         "args": ["unifi-pro-mcp@latest", "--env-file", "/path/to/.env"]
       }
     }
   }
   ```

## 📋 Logging & Debugging

### Enable Debug Logging

1. **Environment variable:**
   ```bash
   export DEBUG=unifi-pro-mcp:*
   ```

2. **Configuration file:**
   ```json
   {
     "logging": {
       "level": "debug",
       "console": true,
       "file": {
         "enabled": true,
         "path": "/tmp/unifi-mcp-debug.log"
       }
     }
   }
   ```

3. **Claude Desktop debug:**
   ```json
   {
     "mcpServers": {
       "unifi-pro": {
         "env": {
           "DEBUG": "unifi-pro-mcp:*",
           "LOG_LEVEL": "debug"
         }
       }
     }
   }
   ```

### Log Analysis

1. **Common log patterns:**
   ```bash
   # Authentication issues
   grep -i "auth" /tmp/unifi-mcp-debug.log
   
   # Connection problems
   grep -i "connect\|timeout\|refused" /tmp/unifi-mcp-debug.log
   
   # API errors
   grep -i "error\|failed" /tmp/unifi-mcp-debug.log
   ```

2. **Real-time monitoring:**
   ```bash
   tail -f /tmp/unifi-mcp-debug.log
   ```

## ❌ Common Error Codes

### HTTP Status Codes

| Code | Description | Common Causes | Solutions |
|------|-------------|---------------|-----------|
| **401** | Unauthorized | Invalid credentials, API access disabled | Check username/password, enable API access |
| **403** | Forbidden | Insufficient permissions, site access denied | Verify user role, check site permissions |
| **404** | Not Found | Wrong endpoint, device not found | Verify API endpoints, check device IDs |
| **408** | Request Timeout | Network issues, server overload | Check connectivity, reduce request frequency |
| **429** | Too Many Requests | Rate limiting active | Implement backoff, reduce request rate |
| **500** | Internal Server Error | UniFi Controller issues | Check controller logs, restart service |
| **502** | Bad Gateway | Proxy/load balancer issues | Check proxy configuration |
| **503** | Service Unavailable | Controller maintenance mode | Wait for maintenance completion |

### Application Error Codes

| Code | Description | Solutions |
|------|-------------|-----------|
| **ECONNREFUSED** | Connection refused | Check if service is running, verify port |
| **ENOTFOUND** | Host not found | Check hostname/IP, verify DNS resolution |
| **ETIMEDOUT** | Connection timeout | Check network connectivity, increase timeout |
| **ECONNRESET** | Connection reset | Check firewall, verify SSL configuration |
| **EPROTO** | Protocol error | Check SSL/TLS configuration |

## 🆘 Support Resources

### Self-Help Resources

1. **Documentation:**
   - [Installation Guide](installation.md)
   - [API Reference](api-reference.md)
   - [Security Guide](security.md)

2. **Debug Tools:**
   ```bash
   # Health check
   npx unifi-pro-mcp@latest --health
   
   # System diagnostics
   npx unifi-pro-mcp@latest --diagnostics
   
   # Export logs
   npx unifi-pro-mcp@latest --export-logs
   ```

### Community Support

1. **GitHub Issues:**
   - [Report bugs](https://github.com/yourusername/unifi-pro-mcp/issues)
   - [Feature requests](https://github.com/yourusername/unifi-pro-mcp/issues)
   - [Q&A discussions](https://github.com/yourusername/unifi-pro-mcp/discussions)

2. **Community Forums:**
   - UniFi Community Forums
   - MCP Community Discord
   - Stack Overflow (tag: unifi-mcp)

### Professional Support

For enterprise customers:
- Priority support channels
- Professional services
- Custom development

### Creating Support Requests

When creating a support request, include:

1. **Environment Information:**
   ```bash
   npx unifi-pro-mcp@latest --version
   node --version
   npm --version
   uname -a
   ```

2. **Configuration (sanitized):**
   - Remove passwords and sensitive data
   - Include relevant configuration sections

3. **Error Details:**
   - Complete error messages
   - Stack traces
   - Log excerpts

4. **Steps to Reproduce:**
   - Detailed reproduction steps
   - Expected vs. actual behavior
   - Frequency of occurrence

**Example Issue Template:**
```markdown
## Environment
- UniFi PRO MCP Version: 1.0.0
- Node.js Version: 18.17.0
- Operating System: Ubuntu 22.04
- UniFi Controller Version: 7.4.162

## Configuration
```json
{
  "controller": {
    "host": "192.168.1.1",
    "port": 8443,
    "username": "[REDACTED]",
    "site": "default"
  }
}
```

## Error Description
Brief description of the issue...

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What you expected to happen...

## Actual Behavior
What actually happened...

## Logs
```
Error log excerpts...
```
```

---

**Remember:** Most issues can be resolved by carefully checking configuration, network connectivity, and credentials. When in doubt, start with the basic diagnostic steps before diving into complex troubleshooting.