# Komodo MCP Server - Troubleshooting Guide
Solutions for common issues when using the Komodo MCP server.
## Table of Contents
1. [Connection Issues](#connection-issues)
2. [Authentication Errors](#authentication-errors)
3. [Tool Execution Failures](#tool-execution-failures)
4. [Performance Issues](#performance-issues)
5. [Configuration Problems](#configuration-problems)
6. [Error Reference](#error-reference)
7. [Diagnostic Tools](#diagnostic-tools)
---
## Connection Issues
### Cannot Connect to Komodo Server
**Symptoms**:
- `ECONNREFUSED` error
- `Network request failed` error
- Timeout errors
**Possible Causes**:
1. **Incorrect URL**
**Solution**:
```bash
# Verify the URL is correct
echo $KOMODO_URL
# Test connection
curl -I $KOMODO_URL
```
Ensure:
- Protocol is correct (`https://` not `http://`)
- No trailing slash
- Port number if non-standard
2. **Komodo Server Not Running**
**Solution**:
```bash
# Check if server is accessible
ping komodo.example.com
# Test HTTP connection
curl -v https://komodo.example.com/health
```
3. **Firewall/Network Issues**
**Solution**:
- Check firewall rules
- Verify network connectivity
- Test from different network
- Check VPN if required
4. **DNS Resolution Failure**
**Solution**:
```bash
# Test DNS resolution
nslookup komodo.example.com
# Try with IP address instead
export KOMODO_URL="https://192.168.1.100:8080"
```
---
### SSL Certificate Errors
**Symptoms**:
- `CERT_NOT_VALID` error
- `SSL certificate problem` error
- `unable to verify the first certificate` error
**Solutions**:
1. **For Development (Temporary)**:
```bash
export KOMODO_SSL_VERIFY=false
```
**Warning**: Only use in development! Never disable SSL verification in production.
2. **For Production (Recommended)**:
Install proper SSL certificate:
```bash
# Add certificate to system trust store
# On macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain cert.pem
# On Linux:
sudo cp cert.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates
```
3. **Self-Signed Certificate**:
If using self-signed certificates, add to Node.js trusted certificates:
```bash
export NODE_EXTRA_CA_CERTS=/path/to/ca-certificates.crt
```
---
### Request Timeouts
**Symptoms**:
- `ETIMEDOUT` error
- `Request timeout` error
- Operations hanging
**Solutions**:
1. **Increase Timeout**:
```bash
export KOMODO_TIMEOUT=60000 # 60 seconds
```
2. **Check Server Performance**:
```bash
# Measure response time
time curl -X GET $KOMODO_URL/api/servers
```
3. **Network Latency**:
- Test from server closer to Komodo instance
- Check network quality
- Consider using CDN/proxy
---
## Authentication Errors
### 401 Unauthorized
**Symptoms**:
```json
{
"error": "Invalid API credentials",
"code": "AUTH_ERROR",
"status": 401
}
```
**Solutions**:
1. **Verify Credentials**:
```bash
echo "API Key: $KOMODO_API_KEY"
echo "API Secret: $KOMODO_API_SECRET"
```
Check:
- API key is correct
- API secret matches the key
- No extra spaces or newlines
- Credentials are not expired
2. **Test Credentials Directly**:
```bash
# Create test signature
timestamp=$(date +%s)
signature=$(echo -n "GET/api/servers$timestamp" | openssl dgst -sha256 -hmac "$KOMODO_API_SECRET" | cut -d' ' -f2)
# Test request
curl -H "X-Komodo-Api-Key: $KOMODO_API_KEY" \
-H "X-Komodo-Timestamp: $timestamp" \
-H "X-Komodo-Signature: $signature" \
$KOMODO_URL/api/servers
```
3. **Regenerate Credentials**:
- Log into Komodo UI
- Navigate to Settings > API Keys
- Generate new key/secret pair
- Update environment variables
---
### 403 Forbidden
**Symptoms**:
```json
{
"error": "Insufficient permissions",
"code": "FORBIDDEN",
"status": 403
}
```
**Solutions**:
1. **Check API Key Permissions**:
- Log into Komodo UI
- Check API key permissions
- Ensure key has required scopes:
- `read:servers`
- `write:deployments`
- `execute:*`
2. **Verify User Role**:
- Ensure user associated with API key has admin or required role
- Check team permissions if using multi-tenancy
3. **Resource-Level Permissions**:
- Verify access to specific server/deployment
- Check tag-based access control
- Review resource ownership
---
### Signature Mismatch
**Symptoms**:
```json
{
"error": "Invalid signature",
"code": "AUTH_ERROR",
"status": 401
}
```
**Possible Causes**:
1. **Clock Drift**:
**Solution**:
```bash
# Sync system time
sudo ntpdate -s time.nist.gov
# Or use timedatectl on Linux
sudo timedatectl set-ntp true
```
2. **Incorrect Secret**:
**Solution**:
- Verify `KOMODO_API_SECRET` is correct
- Check for hidden characters
- Regenerate if uncertain
3. **Encoding Issues**:
**Solution**:
- Ensure secret is UTF-8 encoded
- Check for special characters
- Verify no whitespace in secret
---
## Tool Execution Failures
### 404 Not Found
**Symptoms**:
```json
{
"error": "Server not found: srv_invalid",
"code": "NOT_FOUND",
"status": 404
}
```
**Solutions**:
1. **Verify Resource ID**:
```
# List all servers to find correct ID
"Show me all servers"
```
2. **Check Resource Existence**:
- Resource may have been deleted
- ID may be from different environment
- Check for typos in ID
3. **Use List Tools**:
Always use list tools to discover valid IDs:
- `komodo_read_ListServers`
- `komodo_read_ListDeployments`
- etc.
---
### 400 Validation Error
**Symptoms**:
```json
{
"error": "Missing required field: id",
"code": "VALIDATION_ERROR",
"status": 400
}
```
**Solutions**:
1. **Check Required Parameters**:
- Review [API Reference](./API_REFERENCE.md)
- Ensure all required fields are provided
- Verify parameter types
2. **Validate Parameter Values**:
```json
// Correct
{ "id": "srv_abc123" }
// Incorrect - missing field
{ }
// Incorrect - wrong type
{ "id": 123 }
```
3. **Check Enum Values**:
```json
// Correct
{ "status": "running" }
// Incorrect - invalid enum value
{ "status": "online" }
```
---
### 409 Conflict
**Symptoms**:
```json
{
"error": "Deployment already in progress",
"code": "CONFLICT",
"status": 409
}
```
**Solutions**:
1. **Check Resource Status**:
```
"Get deployment dep_123 status"
```
2. **Wait for Completion**:
- Wait for current operation to finish
- Monitor job status
- Retry after completion
3. **Cancel Existing Operation** (if supported):
- Check Komodo UI for cancel option
- Use appropriate stop/cancel tool
---
### 500 Internal Server Error
**Symptoms**:
```json
{
"error": "Internal server error",
"code": "INTERNAL_ERROR",
"status": 500
}
```
**Solutions**:
1. **Retry Operation**:
- Server automatically retries on 5xx errors
- Wait a few seconds and try again
2. **Check Komodo Server Logs**:
```bash
# View Komodo server logs
docker logs komodo-server
# Or check log files
tail -f /var/log/komodo/server.log
```
3. **Report to Komodo Admin**:
- If persists, contact Komodo administrator
- Provide error details and timestamp
- Include request details (without credentials)
---
## Performance Issues
### Slow Response Times
**Symptoms**:
- Tool calls take >10 seconds
- Timeout warnings
- Laggy interactions
**Solutions**:
1. **Check Network Latency**:
```bash
# Test latency
ping komodo.example.com
# Measure response time
time curl -X GET $KOMODO_URL/api/servers
```
2. **Use Pagination**:
```
# Instead of
"Show all servers"
# Use
"Show first 20 servers"
```
3. **Apply Filters**:
```
# Instead of fetching all and filtering client-side
"Show all deployments" (then filter)
# Filter server-side
"Show running deployments on server srv_123"
```
4. **Optimize Query Frequency**:
- Cache results when appropriate
- Batch related queries
- Avoid polling
---
### High Memory Usage
**Symptoms**:
- Node.js process using excessive memory
- Out of memory errors
- System slowdown
**Solutions**:
1. **Reduce Page Size**:
```bash
# Don't fetch 1000 items at once
# Use smaller page sizes
page_size: 20 # instead of 100
```
2. **Monitor Memory**:
```bash
# Check Node.js memory usage
node --max-old-space-size=512 dist/index.js
```
3. **Restart MCP Server**:
- Restart Claude application
- Reload MCP server configuration
- Clear cache if applicable
---
## Configuration Problems
### Environment Variables Not Loaded
**Symptoms**:
- MCP server fails to start
- Missing configuration errors
- Undefined variable errors
**Solutions**:
1. **Verify Environment Variables**:
```bash
# Check all required vars are set
env | grep KOMODO
```
2. **Check MCP Configuration**:
```json
{
"mcpServers": {
"komodo": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"KOMODO_URL": "https://komodo.example.com",
"KOMODO_API_KEY": "your-key",
"KOMODO_API_SECRET": "your-secret"
}
}
}
}
```
3. **Load from .env File**:
```bash
# Add to shell profile
export $(cat .env | xargs)
```
---
### Wrong Komodo Instance
**Symptoms**:
- Seeing unexpected servers/deployments
- Wrong data returned
- Resources not found
**Solutions**:
1. **Verify URL**:
```bash
echo $KOMODO_URL
# Should match intended instance
```
2. **Use Environment-Specific Configs**:
```json
{
"mcpServers": {
"komodo-prod": {
"env": {
"KOMODO_URL": "https://komodo.prod.example.com"
}
},
"komodo-staging": {
"env": {
"KOMODO_URL": "https://komodo.staging.example.com"
}
}
}
}
```
---
## Error Reference
### Complete Error Code List
| Code | Status | Cause | Solution |
|------|--------|-------|----------|
| `AUTH_ERROR` | 401 | Invalid credentials | Verify API key and secret |
| `FORBIDDEN` | 403 | Insufficient permissions | Check API key permissions |
| `NOT_FOUND` | 404 | Resource doesn't exist | Verify resource ID |
| `VALIDATION_ERROR` | 400 | Invalid input | Check parameters |
| `CONFLICT` | 409 | Resource conflict | Wait for operation to complete |
| `RATE_LIMIT_ERROR` | 429 | Too many requests | Wait and retry |
| `TIMEOUT_ERROR` | 504 | Request timeout | Increase timeout or check server |
| `NETWORK_ERROR` | - | Network failure | Check connectivity |
| `INTERNAL_ERROR` | 500 | Server error | Retry or contact admin |
---
## Diagnostic Tools
### Test Connection
```bash
#!/bin/bash
# test-connection.sh
echo "Testing Komodo MCP Connection"
echo "=============================="
echo
# Check environment variables
echo "1. Checking environment variables..."
if [ -z "$KOMODO_URL" ]; then
echo "❌ KOMODO_URL not set"
exit 1
fi
echo "✅ KOMODO_URL: $KOMODO_URL"
if [ -z "$KOMODO_API_KEY" ]; then
echo "❌ KOMODO_API_KEY not set"
exit 1
fi
echo "✅ KOMODO_API_KEY: ${KOMODO_API_KEY:0:10}..."
if [ -z "$KOMODO_API_SECRET" ]; then
echo "❌ KOMODO_API_SECRET not set"
exit 1
fi
echo "✅ KOMODO_API_SECRET: [HIDDEN]"
echo
# Test DNS resolution
echo "2. Testing DNS resolution..."
host=$(echo $KOMODO_URL | sed -e 's|^[^/]*//||' -e 's|/.*$||')
if nslookup $host > /dev/null 2>&1; then
echo "✅ DNS resolution successful"
else
echo "❌ DNS resolution failed"
exit 1
fi
echo
# Test network connectivity
echo "3. Testing network connectivity..."
if ping -c 1 $host > /dev/null 2>&1; then
echo "✅ Network connectivity OK"
else
echo "⚠️ Ping failed (may be blocked)"
fi
echo
# Test HTTP connection
echo "4. Testing HTTP connection..."
if curl -Is $KOMODO_URL > /dev/null 2>&1; then
echo "✅ HTTP connection successful"
else
echo "❌ HTTP connection failed"
exit 1
fi
echo
# Test API authentication
echo "5. Testing API authentication..."
timestamp=$(date +%s)
signature=$(echo -n "GET/api/servers$timestamp" | openssl dgst -sha256 -hmac "$KOMODO_API_SECRET" | cut -d' ' -f2)
response=$(curl -s -w "\n%{http_code}" \
-H "X-Komodo-Api-Key: $KOMODO_API_KEY" \
-H "X-Komodo-Timestamp: $timestamp" \
-H "X-Komodo-Signature: $signature" \
$KOMODO_URL/api/servers)
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')
if [ "$http_code" = "200" ]; then
echo "✅ Authentication successful"
echo
echo "Connection test passed! ✅"
else
echo "❌ Authentication failed (HTTP $http_code)"
echo "$body"
exit 1
fi
```
Usage:
```bash
chmod +x test-connection.sh
./test-connection.sh
```
---
### Debug Mode
Enable detailed logging:
```bash
# Set log level to debug
export KOMODO_LOG_LEVEL=debug
# Start MCP server (logs to stderr)
node dist/index.js 2> komodo-mcp-debug.log
```
View logs:
```bash
tail -f komodo-mcp-debug.log
```
---
### Network Debugging
```bash
# Capture network traffic
tcpdump -i any -s 0 -w komodo-traffic.pcap host komodo.example.com
# Analyze with Wireshark
wireshark komodo-traffic.pcap
```
---
### Check MCP Server Status
```bash
# Check if MCP server process is running
ps aux | grep "komodo-mcp"
# Check Claude's MCP server status
# (method depends on Claude client)
# Test tool availability
# Ask Claude: "List all available Komodo tools"
```
---
## Getting Help
If you can't resolve an issue:
1. **Check Documentation**:
- [Usage Guide](./USAGE.md)
- [API Reference](./API_REFERENCE.md)
- [Architecture](./ARCHITECTURE.md)
2. **Enable Debug Logging**:
```bash
export KOMODO_LOG_LEVEL=debug
```
3. **Gather Information**:
- Error message and code
- Timestamp of error
- Tool name and parameters
- MCP server logs
- Komodo server version
4. **Report Issue**:
- Create GitHub issue
- Include debug information (without credentials)
- Provide reproduction steps
- Include environment details
5. **Contact Support**:
- Komodo support for server issues
- MCP server maintainers for integration issues
---
## Preventive Measures
### Regular Maintenance
1. **Update Dependencies**:
```bash
npm update
npm audit fix
```
2. **Rotate Credentials**:
- Rotate API keys quarterly
- Use secrets management
- Audit API key usage
3. **Monitor Performance**:
- Track response times
- Monitor error rates
- Set up alerts
4. **Test Regularly**:
```bash
# Run connection test weekly
./test-connection.sh
```
### Best Practices
1. **Use Retry Logic**: Already built-in, but ensure `KOMODO_RETRY_COUNT` is set appropriately
2. **Handle Errors Gracefully**: Always check tool responses for errors
3. **Validate Input**: Use list tools to discover valid IDs before operations
4. **Monitor Rate Limits**: Respect API rate limits to avoid 429 errors
5. **Secure Credentials**: Never log or expose API secrets
6. **Keep Updated**: Update MCP server when new versions are released
