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: Package versions or CVEs do not match the image that runs in the target cluster, especially when Kubescape runs on an ARM laptop and the workload runs on amd64 Nodes, or the reverse.
Solution: Select the OCI platform explicitly for a direct image scan:
kubescape scan image registry.example.com/team/app:v2 --platform linux/amd64
For --scan-images, Kubescape uses collected Node labels and hard workload scheduling constraints when possible. Offline manifests often lack that context, so provide an override:
kubescape scan ./manifests --scan-images --image-platform linux/arm64
The selected platform is shown next to the image in scan summaries. See multi-architecture image scanning for the full inference rules.
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. Kubescape uses your docker config and configured credential helpers by default:
docker login myregistry.io
docker pull myregistry.io/myimage:tag
Use environment variables for credentials when a docker config or credential helper is not available:
export KUBESCAPE_REGISTRY_USERNAME=<registry-username>
export KUBESCAPE_REGISTRY_PASSWORD=<registry-password>
kubescape scan image myregistry.io/myimage:tag
If your registry uses bearer tokens, set KUBESCAPE_REGISTRY_TOKEN instead of username/password.
For kubescape scan --scan-images, also pass --registry-authority myregistry.io so the credentials are only used for that registry.
kubescape patch reads KUBESCAPE_REGISTRY_USERNAME / KUBESCAPE_REGISTRY_PASSWORD too (it has no token flag). Prefer them over --password, which is visible to other users on the host via ps and is written to your shell history:
export KUBESCAPE_REGISTRY_USERNAME=<registry-username>
export KUBESCAPE_REGISTRY_PASSWORD=<registry-password>
kubescape patch --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)