# Troubleshooting Guide
This guide helps you diagnose and resolve common issues with MCP-K8sWizard. It covers installation problems, configuration issues, Kubernetes connectivity problems, and tool-specific troubleshooting.
## Table of Contents
- [Quick Diagnosis](#quick-diagnosis)
- [Installation Issues](#installation-issues)
- [Configuration Problems](#configuration-problems)
- [Kubernetes Connectivity](#kubernetes-connectivity)
- [Tool-Specific Issues](#tool-specific-issues)
- [Performance Problems](#performance-problems)
- [Security Issues](#security-issues)
- [Logging and Debugging](#logging-and-debugging)
- [Common Error Messages](#common-error-messages)
- [Getting Help](#getting-help)
## Quick Diagnosis
### Health Check Commands
```bash
# Check if MCP-K8sWizard is running
ps aux | grep mcp-k8swizard
# Test Kubernetes connectivity
kubectl cluster-info
# Check MCP server status (stdio-based, no HTTP endpoint)
# MCP-K8sWizard runs as a stdio-based MCP server, not HTTP
# Check if process is running instead:
ps aux | grep mcp-k8swizard
# Check version and help
./mcp-k8swizard --version
./mcp-k8swizard --help
# Test Kubernetes connectivity
kubectl cluster-info
```
### Quick Fixes
| Problem | Quick Fix |
|---------|-----------|
| Server won't start | Check port availability and permissions |
| Can't connect to K8s | Verify kubeconfig and context |
| Tools not working | Check RBAC permissions |
| High memory usage | Adjust resource limits |
| Slow responses | Check network connectivity |
## Installation Issues
### Problem: Binary Not Found
**Error:**
```bash
bash: ./mcp-k8swizard: No such file or directory
```
**Solutions:**
1. **Check if binary exists:**
```bash
ls -la ./mcp-k8swizard
```
2. **Rebuild the binary:**
```bash
make build
```
3. **Check file permissions:**
```bash
chmod +x ./mcp-k8swizard
```
4. **Install dependencies:**
```bash
make deps
```
### Problem: Go Version Mismatch
**Error:**
```bash
go: requires go version >= 1.25.1
```
**Solutions:**
1. **Check Go version:**
```bash
go version
```
2. **Update Go:**
```bash
# Using Go installer
go install golang.org/dl/go1.25.1@latest
go1.25.1 download
# Or using package manager
brew install go@1.25.1 # macOS
sudo apt install golang-1.25 # Ubuntu
```
3. **Set Go version:**
```bash
export PATH="/usr/local/go1.25.1/bin:$PATH"
```
### Problem: Build Failures
**Error:**
```bash
go: module github.com/your-org/mcp-k8swizard: cannot find module providing package
```
**Solutions:**
1. **Initialize Go module:**
```bash
go mod init github.com/your-org/mcp-k8swizard
```
2. **Download dependencies:**
```bash
go mod download
go mod tidy
```
3. **Clean and rebuild:**
```bash
make clean
make build
```
### Problem: Permission Denied
**Error:**
```bash
permission denied: cannot execute binary file
```
**Solutions:**
1. **Check file permissions:**
```bash
ls -la ./mcp-k8swizard
chmod +x ./mcp-k8swizard
```
2. **Check if binary is executable:**
```bash
file ./mcp-k8swizard
```
3. **Run with proper user:**
```bash
sudo ./mcp-k8swizard
```
## Configuration Problems
### Problem: Invalid Configuration File
**Error:**
```bash
Error: yaml: unmarshal errors: line 5: cannot unmarshal !!str `invalid` into int
```
**Solutions:**
1. **Validate YAML syntax:**
```bash
yamllint config.yaml
```
2. **Check configuration manually:**
```bash
# MCP-K8sWizard doesn't have built-in config validation
# Check environment variables instead:
echo $KUBECONFIG
echo $K8S_CONTEXT
echo $LOG_LEVEL
```
3. **Use default configuration:**
```bash
# MCP-K8sWizard uses sensible defaults
# No config file required for basic operation
```
### Problem: Missing Environment Variables
**Error:**
```bash
Error: required environment variable KUBECONFIG not set
```
**Solutions:**
1. **Set environment variables:**
```bash
export KUBECONFIG=~/.kube/config
export K8S_CONTEXT=my-context
```
2. **Use configuration file:**
```yaml
kubernetes:
kubeconfig: "~/.kube/config"
context: "my-context"
```
3. **Check .bashrc/.zshrc:**
```bash
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
source ~/.bashrc
```
### Problem: Invalid Kubeconfig
**Error:**
```bash
Error: invalid kubeconfig: context "my-context" does not exist
```
**Solutions:**
1. **List available contexts:**
```bash
kubectl config get-contexts
```
2. **Set correct context:**
```bash
kubectl config use-context correct-context
```
3. **Regenerate kubeconfig:**
```bash
# For EKS
aws eks update-kubeconfig --region us-west-2 --name my-cluster
# For GKE
gcloud container clusters get-credentials my-cluster --zone us-central1-a
# For AKS
az aks get-credentials --resource-group myResourceGroup --name myCluster
```
## Kubernetes Connectivity
### Problem: Connection Refused
**Error:**
```bash
Error: Get "https://kubernetes.default.svc/api": dial tcp: connection refused
```
**Solutions:**
1. **Check if cluster is running:**
```bash
kubectl cluster-info
```
2. **Verify kubeconfig:**
```bash
kubectl config view
```
3. **Test with kubectl:**
```bash
kubectl get nodes
```
4. **Check network connectivity:**
```bash
ping kubernetes.default.svc
telnet kubernetes.default.svc 443
```
### Problem: Authentication Failed
**Error:**
```bash
Error: Unauthorized (401): Unauthorized
```
**Solutions:**
1. **Check token validity:**
```bash
kubectl auth can-i get pods
```
2. **Refresh credentials:**
```bash
# For AWS EKS
aws eks update-kubeconfig --region us-west-2 --name my-cluster
# For GKE
gcloud auth login
gcloud container clusters get-credentials my-cluster
```
3. **Check RBAC permissions:**
```bash
kubectl auth can-i --list
```
### Problem: Certificate Issues
**Error:**
```bash
Error: x509: certificate signed by unknown authority
```
**Solutions:**
1. **Skip TLS verification (development only):**
```bash
export K8S_INSECURE_SKIP_TLS=true
```
2. **Update CA certificate:**
```bash
kubectl config set-cluster my-cluster --certificate-authority=/path/to/ca.crt
```
3. **Regenerate kubeconfig:**
```bash
aws eks update-kubeconfig --region us-west-2 --name my-cluster
```
### Problem: Context Not Found
**Error:**
```bash
Error: context "my-context" does not exist
```
**Solutions:**
1. **List available contexts:**
```bash
kubectl config get-contexts
```
2. **Set current context:**
```bash
kubectl config use-context available-context
```
3. **Create new context:**
```bash
kubectl config set-context my-context --cluster=my-cluster --user=my-user
```
## Tool-Specific Issues
### Problem: k8s_get_pods Fails
**Error:**
```bash
Error: pods is forbidden: User "system:serviceaccount:default:mcp-k8swizard" cannot list resource "pods"
```
**Solutions:**
1. **Check RBAC permissions:**
```bash
kubectl auth can-i list pods
```
2. **Update service account permissions:**
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: mcp-k8swizard
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: mcp-k8swizard
subjects:
- kind: ServiceAccount
name: mcp-k8swizard
namespace: default
```
3. **Check namespace permissions:**
```bash
kubectl auth can-i list pods --namespace=default
```
### Problem: kubectl_exec_in_pod Fails
**Error:**
```bash
Error: pods "my-pod" not found
```
**Solutions:**
1. **Check if pod exists:**
```bash
kubectl get pods
```
2. **Check pod status:**
```bash
kubectl describe pod my-pod
```
3. **Verify namespace:**
```bash
kubectl get pods --all-namespaces | grep my-pod
```
### Problem: k8s_get_logs Fails
**Error:**
```bash
Error: container "my-container" in pod "my-pod" is not available
```
**Solutions:**
1. **Check container status:**
```bash
kubectl describe pod my-pod
```
2. **List containers in pod:**
```bash
kubectl get pod my-pod -o jsonpath='{.spec.containers[*].name}'
```
3. **Check container logs directly:**
```bash
kubectl logs my-pod -c my-container
```
## Performance Problems
### Problem: High Memory Usage
**Symptoms:**
- Memory usage > 1GB
- Slow response times
- Out of memory errors
**Solutions:**
1. **Check memory limits:**
```bash
kubectl top pods -n kube-system
```
2. **Adjust resource limits:**
```yaml
resources:
limits:
memory: "512Mi"
requests:
memory: "256Mi"
```
3. **Enable garbage collection:**
```bash
export GOGC=100
```
### Problem: Slow API Responses
**Symptoms:**
- API calls taking > 30 seconds
- Timeout errors
- High latency
**Solutions:**
1. **Check network connectivity:**
```bash
ping kubernetes.default.svc
traceroute kubernetes.default.svc
```
2. **Adjust timeout settings:**
```bash
export K8S_TIMEOUT=60
```
3. **Check cluster health:**
```bash
kubectl get nodes
kubectl top nodes
```
### Problem: Connection Pool Exhaustion
**Error:**
```bash
Error: too many open connections
```
**Solutions:**
1. **Adjust connection pool settings:**
```yaml
connection_pool:
max_idle_connections: 50
max_connections_per_host: 5
```
2. **Enable connection reuse:**
```bash
export K8S_QPS=20
export K8S_BURST=40
```
3. **Check for connection leaks:**
```bash
netstat -an | grep :443 | wc -l
```
## Security Issues
### Problem: TLS Certificate Errors
**Error:**
```bash
Error: x509: certificate has expired or is not yet valid
```
**Solutions:**
1. **Check certificate validity:**
```bash
openssl x509 -in /path/to/cert.crt -text -noout
```
2. **Update certificate:**
```bash
kubectl config set-cluster my-cluster --certificate-authority=/path/to/new-ca.crt
```
3. **Skip TLS verification (development only):**
```bash
export K8S_INSECURE_SKIP_TLS=true
```
### Problem: Authentication Token Expired
**Error:**
```bash
Error: Unauthorized (401): token has expired
```
**Solutions:**
1. **Refresh token:**
```bash
# For AWS EKS
aws eks update-kubeconfig --region us-west-2 --name my-cluster
# For GKE
gcloud auth login
gcloud container clusters get-credentials my-cluster
```
2. **Check token expiration:**
```bash
kubectl config view --raw -o jsonpath='{.users[0].user.token}' | base64 -d
```
3. **Use service account token:**
```bash
kubectl create token mcp-k8swizard
```
### Problem: RBAC Permission Denied
**Error:**
```bash
Error: pods is forbidden: User "system:serviceaccount:default:mcp-k8swizard" cannot list resource "pods"
```
**Solutions:**
1. **Check current permissions:**
```bash
kubectl auth can-i --list
```
2. **Create proper RBAC:**
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: mcp-k8swizard
rules:
- apiGroups: [""]
resources: ["pods", "services", "endpoints"]
verbs: ["get", "list", "watch"]
```
3. **Bind role to service account:**
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: mcp-k8swizard
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: mcp-k8swizard
subjects:
- kind: ServiceAccount
name: mcp-k8swizard
namespace: default
```
## Logging and Debugging
### Enable Debug Logging
```bash
# Set debug level
export LOG_LEVEL=DEBUG
# Enable verbose mode
./mcp-k8swizard --verbose
# Log to file
export LOG_FILE=/var/log/mcp-k8swizard.log
```
### Common Debug Commands
```bash
# Check server logs
tail -f /var/log/mcp-k8swizard.log
# Check Kubernetes events
kubectl get events --sort-by='.lastTimestamp'
# Check pod logs
kubectl logs -l app=mcp-k8swizard
# Check resource usage
kubectl top pods -l app=mcp-k8swizard
```
### Debugging Tools
1. **Network debugging:**
```bash
# Check connectivity
telnet kubernetes.default.svc 443
# Check DNS resolution
nslookup kubernetes.default.svc
# Check routing
traceroute kubernetes.default.svc
```
2. **Kubernetes debugging:**
```bash
# Check cluster info
kubectl cluster-info dump
# Check API server logs
kubectl logs -n kube-system -l component=kube-apiserver
# Check etcd logs
kubectl logs -n kube-system -l component=etcd
```
3. **Application debugging:**
```bash
# Check application logs
kubectl logs -l app=mcp-k8swizard
# Check resource usage
kubectl top pods -l app=mcp-k8swizard
# Check pod status
kubectl describe pod -l app=mcp-k8swizard
```
## Common Error Messages
### Error: "context was not found for specified context"
**Cause:** Invalid or missing Kubernetes context
**Solution:**
```bash
# List available contexts
kubectl config get-contexts
# Set correct context
kubectl config use-context correct-context
```
### Error: "getting credentials: exec: executable aws failed with exit code 255"
**Cause:** AWS CLI not installed or configured
**Solution:**
```bash
# Install AWS CLI
pip install awscli
# Configure AWS CLI
aws configure
# Update kubeconfig
aws eks update-kubeconfig --region us-west-2 --name my-cluster
```
### Error: "dial tcp: connection refused"
**Cause:** Kubernetes API server not accessible
**Solution:**
```bash
# Check if cluster is running
kubectl cluster-info
# Check network connectivity
ping kubernetes.default.svc
# Verify kubeconfig
kubectl config view
```
### Error: "pods is forbidden: User cannot list resource"
**Cause:** Insufficient RBAC permissions
**Solution:**
```bash
# Check current permissions
kubectl auth can-i list pods
# Create proper RBAC
kubectl apply -f rbac.yaml
```
### Error: "container is not available"
**Cause:** Container not found or not running
**Solution:**
```bash
# Check pod status
kubectl describe pod my-pod
# List containers
kubectl get pod my-pod -o jsonpath='{.spec.containers[*].name}'
# Check container logs
kubectl logs my-pod -c my-container
```
## Getting Help
### Self-Help Resources
1. **Check logs:**
```bash
tail -f /var/log/mcp-k8swizard.log
```
2. **Check configuration:**
```bash
echo "KUBECONFIG: $KUBECONFIG"
echo "K8S_CONTEXT: $K8S_CONTEXT"
echo "LOG_LEVEL: $LOG_LEVEL"
```
3. **Test connectivity:**
```bash
kubectl cluster-info
```
4. **Check MCP server status:**
```bash
# MCP-K8sWizard runs as stdio-based server
ps aux | grep mcp-k8swizard
```
### Community Support
1. **GitHub Issues:** [Report bugs and request features](https://github.com/your-org/mcp-k8swizard/issues)
2. **GitHub Discussions:** [Ask questions and share solutions](https://github.com/your-org/mcp-k8swizard/discussions)
3. **Documentation:** [Complete documentation](https://github.com/your-org/mcp-k8swizard/wiki)
### Professional Support
For enterprise support and consulting:
- **Email:** support@your-org.com
- **Slack:** #mcp-k8swizard-support
- **Phone:** +1-800-MCP-K8S1
### Reporting Issues
When reporting issues, please include:
1. **Environment information:**
```bash
./mcp-k8swizard --version
kubectl version
go version
```
2. **Configuration:**
```bash
echo "KUBECONFIG: $KUBECONFIG"
echo "K8S_CONTEXT: $K8S_CONTEXT"
echo "LOG_LEVEL: $LOG_LEVEL"
```
3. **Logs:**
```bash
./mcp-k8swizard --verbose 2>&1 | tee debug.log
```
4. **Steps to reproduce:**
- What command did you run?
- What was the expected result?
- What was the actual result?
5. **Error messages:**
- Full error output
- Stack trace (if available)
## Prevention Tips
1. **Regular Updates:** Keep MCP-K8sWizard and dependencies updated
2. **Monitoring:** Set up monitoring for resource usage and errors
3. **Backups:** Regular backups of configuration files
4. **Testing:** Test changes in development environment first
5. **Documentation:** Keep track of custom configurations
6. **Security:** Regular security audits and updates
7. **Performance:** Monitor performance metrics and optimize as needed
## Next Steps
- [Installation Manual](installation.md) - Complete setup guide
- [Configuration Guide](configuration.md) - Advanced configuration options
- [API Reference](api-reference.md) - Complete tool documentation