Troubleshooting

Common issues and solutions for Kyverno MCP

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

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:

  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