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:

1. Check if the binary is in your PATH:

   echo $PATH
   

2. If using Homebrew, ensure it’s properly linked:

   brew link kyverno-mcp
   

3. 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:

1. Verify kubeconfig exists:

   ls ~/.kube/config
   

2. Test kubectl connection:

   kubectl cluster-info
   

3. Specify kubeconfig explicitly:

   kyverno-mcp --kubeconfig=/path/to/your/kubeconfig
   

4. Check kubeconfig permissions:

   chmod 600 ~/.kube/config
   

Context Not Found

Problem: “context not found” error when switching contexts.

Solution:

1. List available contexts:

   kubectl config get-contexts
   

2. 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:

1. Check configuration file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Validate JSON syntax:

   # Use jq or similar tool
   jq . claude_desktop_config.json
   

3. Ensure correct path:

   {
     "mcpServers": {
       "kyverno": {
         "command": "/usr/local/bin/kyverno-mcp",  // Full path
         "args": ["--kubeconfig=/Users/username/.kube/config"]
       }
     }
   }
   

4. Restart Claude Desktop after configuration changes

Tools Not Available

Problem: AI assistant says Kyverno tools are not available.

Solution:

1. Check if the server is running properly
2. Look for error messages in Claude Desktop logs
3. 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:

1. Check Kyverno installation:

   kubectl get pods -n kyverno
   

2. Verify cluster permissions:

   kubectl auth can-i create clusterpolicies
   

3. Check for existing policies:

   kubectl get cpol
   

4. Look for policy conflicts:

   kubectl describe cpol <policy-name>
   

No Violations Showing

Problem: show_violations returns empty results despite policy violations.

Solutions:

1. Verify PolicyReport CRDs are installed:

   kubectl get crd | grep policyreport
   

2. Check if reports are being generated:

   kubectl get policyreport -A
   kubectl get clusterpolicyreport
   

3. 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:

1. Verify certificate validity:

   openssl x509 -in cert.pem -text -noout
   

2. Check certificate matches the hostname:

   openssl s_client -connect kyverno-mcp.example.com:8443
   

3. Ensure proper certificate chain if using CA-signed certs

Port Already in Use

Problem: “address already in use” error.

Solution:

1. Find what’s using the port:

   lsof -i :8443  # macOS/Linux
   netstat -ano | findstr :8443  # Windows
   

2. 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:

1. Check cluster latency:

   time kubectl get nodes
   

2. Reduce resource queries:

   • Use namespace filters when checking violations
   • Apply policies to specific namespaces first

3. 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

Getting Help

If you’re still experiencing issues:

1. Check existing issues: GitHub Issues
2. Enable debug logging and collect logs
3. Gather environment information:

   kyverno-mcp --version
   kubectl version
   go version  # if built from source
   

4. Create a detailed issue with:
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details
   • Relevant logs

Next Steps

• Review Configuration Options