docs/troubleshooting.md
This guide covers common issues you may encounter when using Kubescape and how to resolve them.
Symptom: After running the install script, kubescape command is not found.
Solution:
Check if the binary was installed:
ls -la ~/.kubescape/kubescape
Add to your PATH:
# For bash
echo 'export PATH=$PATH:~/.kubescape' >> ~/.bashrc
source ~/.bashrc
# For zsh
echo 'export PATH=$PATH:~/.kubescape' >> ~/.zshrc
source ~/.zshrc
Alternatively, move the binary to a directory already in your PATH:
sudo mv ~/.kubescape/kubescape /usr/local/bin/
Symptom: Installation fails with permission errors.
Solution:
# Create the directory with proper permissions
mkdir -p ~/.kubescape
chmod 755 ~/.kubescape
# Re-run the installation
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
Symptom: PowerShell script fails to execute.
Solution:
Check PowerShell version (must be v5.0+):
$PSVersionTable.PSVersion
Set execution policy:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Retry installation:
iwr -useb https://raw.githubusercontent.com/kubescape/kubescape/master/install.ps1 | iex
Symptom: kubescape scan fails with connection errors.
Solutions:
Verify kubectl works:
kubectl get nodes
Check your kubeconfig:
kubectl config current-context
kubectl config view
Use an explicit kubeconfig:
kubescape scan --kubeconfig /path/to/kubeconfig
Use a specific context:
kubescape scan --kube-context my-context
Symptom: Scanning large clusters takes too long or times out.
Solutions:
Scan specific namespaces:
kubescape scan --include-namespaces production,staging
Exclude non-essential namespaces:
kubescape scan --exclude-namespaces kube-system,kube-public,monitoring
Scan a specific framework instead of all:
kubescape scan framework nsa
Symptom: Scan completes but shows no results.
Solutions:
Check if the cluster has workloads:
kubectl get pods --all-namespaces
Run with verbose output:
kubescape scan -v
Check for namespace filtering issues:
# Make sure you're not excluding all namespaces
kubescape scan --include-namespaces default
Symptom: Error about unknown framework or control.
Solutions:
List available frameworks:
kubescape list frameworks
List available controls:
kubescape list controls
Update Kubescape to get latest controls:
# Re-run installation to get latest version
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
Download latest artifacts:
kubescape download artifacts
Symptom: Scan fails with permission denied errors.
Solution:
Ensure your kubeconfig user has sufficient permissions. At minimum, you need read access to:
Symptom: kubescape scan image fails to find the image.
Solutions:
Use the full image reference:
kubescape scan image docker.io/library/nginx:1.21
For private registries, provide credentials:
kubescape scan image myregistry.io/myimage:tag \
--username myuser \
--password mypassword
Check if the image exists locally:
docker images | grep myimage
Symptom: Scan fails with authentication errors.
Solutions:
Verify credentials work with docker:
docker login myregistry.io
docker pull myregistry.io/myimage:tag
Use environment variables for credentials:
export KUBESCAPE_REGISTRY_USERNAME=myuser
export KUBESCAPE_REGISTRY_PASSWORD=mypassword
kubescape scan image myregistry.io/myimage:tag
Symptom: Known CVEs are not being detected.
Solution:
The vulnerability database is updated automatically. To force an update:
# Clear the cache
rm -rf ~/.kubescape/grype-db
# Run a new scan
kubescape scan image nginx:latest
Symptom: kubescape patch fails with BuildKit connection errors.
Solutions:
Start BuildKit:
sudo buildkitd &
Or run BuildKit in Docker:
docker run --detach --rm --privileged \
-p 127.0.0.1:8888:8888/tcp \
--name buildkitd \
--entrypoint buildkitd \
moby/buildkit:latest \
--addr tcp://0.0.0.0:8888
kubescape patch -i nginx:1.22 -a tcp://0.0.0.0:8888
Check BuildKit socket:
ls -la /run/buildkit/buildkitd.sock
Symptom: Patch command reports no patches available.
Explanation: Image patching only fixes OS-level vulnerabilities that have available patches. Application-level vulnerabilities or vulnerabilities without fixes cannot be patched.
Solution:
Check the vulnerability report:
kubescape scan image myimage:tag -v
Look for vulnerabilities marked as "wont-fix" or without fix versions.
Consider updating the base image to a newer version.
Symptom: Patch fails with permission errors.
Solution:
Run with sudo when using the default Unix socket:
sudo kubescape patch --image nginx:1.22
Or use the Docker-based BuildKit approach which doesn't require sudo.
Symptom: kubescape operator scan hangs or fails.
Solutions:
Verify the operator is installed:
kubectl -n kubescape get pods
Check operator logs:
kubectl -n kubescape logs -l app=kubescape-operator
Verify the operator service:
kubectl -n kubescape get svc
Symptom: No VulnerabilityManifest CRs found.
Solutions:
Check if vulnerability scanning is enabled:
kubectl -n kubescape get configmap kubescape-config -o yaml
Verify kubevuln is running:
kubectl -n kubescape get pods -l app=kubevuln
Check kubevuln logs:
kubectl -n kubescape logs -l app=kubevuln
Symptom: kubescape mcpserver exits with errors.
Solutions:
Verify kubectl connectivity:
kubectl get nodes
Check if the operator CRDs are installed:
kubectl get crd vulnerabilitymanifests.spdx.softwarecomposition.kubescape.io
kubectl get crd workloadconfigurationscans.spdx.softwarecomposition.kubescape.io
Install the Kubescape operator if not present:
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm upgrade --install kubescape kubescape/kubescape-operator \
--namespace kubescape --create-namespace
Symptom: AI tool reports connection failures.
Solutions:
Verify the MCP server is running:
kubescape mcpserver
Check your AI tool's MCP configuration:
{
"mcpServers": {
"kubescape": {
"command": "kubescape",
"args": ["mcpserver"]
}
}
}
Ensure kubescape is in your PATH.
Symptom: JSON output cannot be parsed.
Solution:
Ensure you're redirecting to a file, not mixing with console output:
kubescape scan --format json --output results.json
Symptom: SARIF output not working.
Note: SARIF format is only supported for file/repository scans, not live cluster scans.
Solution:
# This works
kubescape scan /path/to/manifests --format sarif --output results.sarif
# This does NOT work
kubescape scan --format sarif --output results.sarif # cluster scan
Symptom: Report generation fails or produces empty files.
Solutions:
Ensure you have write permissions to the output directory.
Check available disk space.
Try JSON first to verify scan works:
kubescape scan --format json --output test.json
Solutions:
Scan fewer namespaces:
kubescape scan --include-namespaces production
Scan one framework at a time:
kubescape scan framework nsa
Use the operator for large clusters instead of CLI scanning.
Solutions:
Use offline mode with pre-downloaded artifacts:
# On a machine with good connectivity
kubescape download artifacts --output /path/to/artifacts
# On the target machine
kubescape scan --use-artifacts-from /path/to/artifacts
Configure a proxy if needed:
export HTTPS_PROXY=http://proxy:8080
kubescape scan
If you're still experiencing issues:
Check the logs with debug logging:
kubescape scan -l debug
Search existing issues: https://github.com/kubescape/kubescape/issues
Join the community Slack:
Open a new issue with:
kubescape version)kubectl version)kubescape scan -l debug 2>&1 | tee debug.log)