Troubleshooting
Common Issues
This guide covers common issues you might encounter when using Kyverno MCP and their solutions.
Installation Issues
Command Not Found
Problem: After installation, kyverno-mcp
command is not found.
Solution:
- Check if the binary is in your PATH:
echo $PATH
- If using Homebrew, ensure it’s properly linked:
brew link kyverno-mcp
- For manual installation, add to PATH:
export PATH=$PATH:/path/to/kyverno-mcp echo 'export PATH=$PATH:/path/to/kyverno-mcp' >> ~/.bashrc
Permission Denied
Problem: Getting “permission denied” when trying to run kyverno-mcp.
Solution:
chmod +x kyverno-mcp
Connection Issues
Cannot Connect to Kubernetes Cluster
Problem: Error messages like “unable to connect to cluster” or “no configuration has been provided”.
Solutions:
-
Verify kubeconfig exists:
ls ~/.kube/config
-
Test kubectl connection:
kubectl cluster-info
-
Specify kubeconfig explicitly:
kyverno-mcp --kubeconfig=/path/to/your/kubeconfig
-
Check kubeconfig permissions:
chmod 600 ~/.kube/config
Context Not Found
Problem: “context not found” error when switching contexts.
Solution:
- List available contexts:
kubectl config get-contexts
- Use the exact context name from the list
MCP Client Issues
Server Not Appearing in Claude Desktop
Problem: Kyverno MCP server doesn’t show up in Claude Desktop.
Solutions:
-
Check configuration file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Validate JSON syntax:
# Use jq or similar tool jq . claude_desktop_config.json
-
Ensure correct path:
{ "mcpServers": { "kyverno": { "command": "/usr/local/bin/kyverno-mcp", // Full path "args": ["--kubeconfig=/Users/username/.kube/config"] } } }
-
Restart Claude Desktop after configuration changes
Tools Not Available
Problem: AI assistant says Kyverno tools are not available.
Solution:
- Check if the server is running properly
- Look for error messages in Claude Desktop logs
- Try running kyverno-mcp directly to see any errors:
kyverno-mcp --kubeconfig=/path/to/config
Policy Issues
Policies Not Being Applied
Problem: Running apply_policies
but policies don’t appear in the cluster.
Solutions:
-
Check Kyverno installation:
kubectl get pods -n kyverno
-
Verify cluster permissions:
kubectl auth can-i create clusterpolicies
-
Check for existing policies:
kubectl get cpol
-
Look for policy conflicts:
kubectl describe cpol <policy-name>
No Violations Showing
Problem: show_violations
returns empty results despite policy violations.
Solutions:
-
Verify PolicyReport CRDs are installed:
kubectl get crd | grep policyreport
-
Check if reports are being generated:
kubectl get policyreport -A kubectl get clusterpolicyreport
-
Ensure policies are in enforce mode:
kubectl get cpol -o yaml | grep validationFailureAction
Network Mode Issues
TLS Certificate Errors
Problem: TLS handshake errors when using HTTPS mode.
Solution:
-
Verify certificate validity:
openssl x509 -in cert.pem -text -noout
-
Check certificate matches the hostname:
openssl s_client -connect kyverno-mcp.example.com:8443
-
Ensure proper certificate chain if using CA-signed certs
Port Already in Use
Problem: “address already in use” error.
Solution:
-
Find what’s using the port:
lsof -i :8443 # macOS/Linux netstat -ano | findstr :8443 # Windows
-
Kill the process or use a different port:
kyverno-mcp --http-addr :8444
Performance Issues
Slow Response Times
Problem: Tools taking a long time to respond.
Solutions:
-
Check cluster latency:
time kubectl get nodes
-
Reduce resource queries:
- Use namespace filters when checking violations
- Apply policies to specific namespaces first
-
Check resource limits if running in a container
Debugging Tips
Enable Debug Logging
Get more detailed output:
kyverno-mcp --log-level=debug
Check MCP Protocol Messages
For stdio mode, you can intercept messages:
# Create a wrapper script
cat > debug-kyverno-mcp.sh << 'EOF'
#!/bin/bash
tee -a kyverno-mcp-input.log | kyverno-mcp "$@" | tee -a kyverno-mcp-output.log
EOF
chmod +x debug-kyverno-mcp.sh
Common Error Messages
Error | Meaning | Solution |
---|---|---|
no kind "ClusterPolicy" is registered |
Kyverno CRDs not installed | Install Kyverno first |
unauthorized |
Insufficient permissions | Check RBAC settings |
context deadline exceeded |
Network timeout | Check connectivity |
certificate signed by unknown authority |
Custom CA not trusted | Add CA to trust store |
Getting Help
If you’re still experiencing issues:
- Check existing issues: GitHub Issues
- Enable debug logging and collect logs
- Gather environment information:
kyverno-mcp --version kubectl version go version # if built from source
- Create a detailed issue with:
- Steps to reproduce
- Expected vs actual behavior
- Environment details
- Relevant logs
Next Steps
- Review Configuration Options