---
title: "Troubleshooting"
description: "Common issues and solutions for Kyverno MCP"
diataxis: how-to
applies_to:
  product: "kyverno"
audience: ["platform-engineer","devsecops"]
last_updated: 2026-03-25
url: https://docs.nirmata.io/docs/controllers/n4k/kyverno-mcp/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:
   ```bash
   echo $PATH
   ```
2. If using Homebrew, ensure it's properly linked:
   ```bash
   brew link kyverno-mcp
   ```
3. For manual installation, add to PATH:
   ```bash
   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**:
```bash
chmod +x kyverno-mcp
```text

## 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**:
   ```bash
   ls ~/.kube/config
   ```

2. **Test kubectl connection**:
   ```bash
   kubectl cluster-info
   ```

3. **Specify kubeconfig explicitly**:
   ```bash
   kyverno-mcp --kubeconfig=/path/to/your/kubeconfig
   ```

4. **Check kubeconfig permissions**:
   ```bash
   chmod 600 ~/.kube/config
   ```

### Context Not Found

**Problem**: "context not found" error when switching contexts.

**Solution**:
1. List available contexts:
   ```bash
   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**:
   ```bash
   # Use jq or similar tool
   jq . claude_desktop_config.json
   ```

3. **Ensure correct path**:
   ```json
   {
     "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:
   ```bash
   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**:
   ```bash
   kubectl get pods -n kyverno
   ```

2. **Verify cluster permissions**:
   ```bash
   kubectl auth can-i create clusterpolicies
   ```

3. **Check for existing policies**:
   ```bash
   kubectl get cpol
   ```

4. **Look for policy conflicts**:
   ```bash
   kubectl describe cpol <policy-name>
   ```

### No Violations Showing

**Problem**: `show_violations` returns empty results despite policy violations.

**Solutions**:

1. **Verify PolicyReport CRDs are installed**:
   ```bash
   kubectl get crd | grep policyreport
   ```

2. **Check if reports are being generated**:
   ```bash
   kubectl get policyreport -A
   kubectl get clusterpolicyreport
   ```

3. **Ensure policies are in enforce mode**:
   ```bash
   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:
   ```bash
   openssl x509 -in cert.pem -text -noout
   ```

2. Check certificate matches the hostname:
   ```bash
   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:
   ```bash
   lsof -i :8443  # macOS/Linux
   netstat -ano | findstr :8443  # Windows
   ```

2. Kill the process or use a different port:
   ```bash
   kyverno-mcp --http-addr :8444
   ```

## Performance Issues

### Slow Response Times

**Problem**: Tools taking a long time to respond.

**Solutions**:

1. **Check cluster latency**:
   ```bash
   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:
```bash
kyverno-mcp --log-level=debug
```text

### Check MCP Protocol Messages

For stdio mode, you can intercept messages:
```bash
# 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](https://github.com/nirmata/kyverno-mcp/issues)
2. **Enable debug logging** and collect logs
3. **Gather environment information**:
   ```bash
   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](configuration.md)