Troubleshooting

This guide covers the most common issues you may encounter when using Kubeasy and how to resolve them.

Installation

CLI binary not found after installation

Problem: Running kubeasy returns "command not found" after downloading the binary.

# Check if the binary location is in your PATH
echo $PATH

# Move the binary to a location in your PATH
sudo mv kubeasy /usr/local/bin/

# Or add the directory to your PATH permanently
echo 'export PATH=$PATH:/path/to/dir' >> ~/.zshrc
source ~/.zshrc

Permission denied when running CLI

Problem: bash: ./kubeasy: Permission denied

chmod +x kubeasy

macOS blocks the binary

Problem: macOS shows "kubeasy cannot be opened because the developer cannot be verified."

xattr -d com.apple.quarantine /usr/local/bin/kubeasy

Or: System Settings → Privacy & Security → Allow Anyway

Cluster setup

Docker not running

Problem: kubeasy setup fails with "Cannot connect to the Docker daemon."

# Verify Docker is running
docker ps

# Start Docker (Linux)
sudo systemctl start docker

On macOS/Windows, start Docker Desktop and wait for it to fully start.

Kind cluster creation fails

Problem: kubeasy setup fails with cluster creation errors.

Port already in use:

lsof -i :6443
kind delete cluster --name kubeasy
kubeasy setup

Insufficient Docker resources:
Go to Docker Desktop → Settings → Resources. Recommended: at least 4 GB RAM and 2 CPUs.

Existing cluster with same name:

kind get clusters
kind delete cluster --name kubeasy
kubeasy setup

kubectl not configured

Problem: kubectl commands fail with "connection refused."

# Verify the Kind cluster is running
kind get clusters

# Re-run setup to reconfigure kubectl
kubeasy setup

Authentication

Generate a new API key from kubeasy.dev/profile
Ensure you copied the full key with no extra spaces
Re-run kubeasy login

API key not found

Problem: Commands fail with "no API key found, please run 'kubeasy login'."

kubeasy login

Credentials are stored at:

macOS/Linux: ~/.config/kubeasy-cli/credentials (or system keyring)
Windows: %APPDATA%/kubeasy-cli/credentials

For CI environments, set KUBEASY_API_KEY as an environment variable.

Challenges

Challenge fails to start

Step 1: Check the cluster is healthy

kubectl get nodes
kubectl get pods -A
kubectl get pods -n kyverno   # Kyverno must be running

Step 2: Check for events in the namespace

kubectl get events -n <challenge-slug> --sort-by='.lastTimestamp'

Step 3: Verify you're authenticated

kubeasy login

Challenge resources not deploying

kubectl get all -n <challenge-slug>
kubectl get events -n <challenge-slug>

# Try resetting and restarting
kubeasy challenge reset <challenge-slug>
kubeasy challenge start <challenge-slug>

Validation fails unexpectedly

Step 1: Resubmit and read the output carefully — each failed objective includes a message explaining why.

Step 2: Inspect the resource state directly:

kubectl get all -n <challenge-slug>
kubectl describe pod <pod-name> -n <challenge-slug>
kubectl logs <pod-name> -n <challenge-slug>
kubectl get events -n <challenge-slug> --sort-by='.lastTimestamp'

Step 3: For connectivity objectives, test manually:

kubectl run -it --rm debug --image=curlimages/curl --restart=Never -n <challenge-slug> \
  -- curl -v http://service-name:port

Kyverno blocks a legitimate change

Problem: Kubernetes rejects your change with a Kyverno policy violation message.

This is expected behavior — Kyverno policies in challenges prevent bypasses (e.g., swapping the broken app with a working one). They protect specific fields like container images.

Read the error message carefully — it tells you what's protected and why. Then focus on fixing the actual problem rather than the protected field.

# View active policies
kubectl get clusterpolicies
kubectl describe clusterpolicy <policy-name>

Challenge stuck in "In Progress"

Submit your solution to update progress:

kubeasy challenge submit <challenge-slug>

If submission succeeds but the web UI hasn't updated, wait a few seconds and refresh.

Network issues

Services not reachable

Step 1: Verify the service exists and has endpoints

kubectl get svc -n <challenge-slug>
kubectl get endpoints <service-name> -n <challenge-slug>

Empty endpoints indicate the pod labels don't match the service selector:

kubectl get pods -n <challenge-slug> --show-labels
kubectl get svc <service-name> -n <challenge-slug> -o yaml | grep -A5 selector

Step 2: Test connectivity from inside the cluster

kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -n <challenge-slug>
# Inside the pod:
curl http://service-name:port
nslookup service-name

Step 3: Check for NetworkPolicies

kubectl get networkpolicies -n <challenge-slug>
kubectl describe networkpolicy <policy-name> -n <challenge-slug>

Pods stuck in ImagePullBackOff

kubectl describe pod <pod-name> -n <challenge-slug>

Common causes: image name typo, private registry without credentials, or Docker Hub rate limiting (wait or authenticate).

Performance

Cluster running slowly

Check Docker resource usage:

docker stats

Increase Docker Desktop resources (Settings → Resources). Recommended: 4–8 GB RAM, 2–4 CPUs.

Clean up unused challenge namespaces:

kubeasy challenge clean <old-challenge>

Check node pressure:

kubectl describe node kubeasy-control-plane

Cleanup issues

Namespace stuck in Terminating

# Check for finalizers blocking deletion
kubectl get namespace <challenge-slug> -o yaml

# Remove finalizers if stuck
kubectl patch namespace <challenge-slug> \
  -p '{"metadata":{"finalizers":[]}}' --type=merge

Reset the cluster completely

kind delete cluster --name kubeasy
kubeasy setup

Clear CLI credentials

# macOS/Linux
rm -rf ~/.config/kubeasy-cli/

# Log in again
kubeasy login

Useful diagnostic commands

# All resources across namespaces
kubectl get all -A

# Recent events (last 20)
kubectl get events -A --sort-by='.lastTimestamp' | tail -20

# Kubeasy component health
kubectl get pods -n kyverno
kubectl get pods -n ingress-nginx
kubectl get pods -n cert-manager
kubectl get pods -n local-path-storage

# Cluster resource usage
kubectl top nodes
kubectl top pods -A

# DNS check
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default

Getting more help

If your issue isn't covered here:

Check the CLI version: kubeasy version
Gather cluster state: kubectl get all -A > cluster-state.yaml
Open an issue: github.com/kubeasy-dev/kubeasy-cli/issues

Include: your error message, CLI version, OS, and what you've already tried.

Troubleshooting

On this page