Why Kubernetes is Blocking Your ImageYou’ve just built a fresh container image locally and you're ready to test it. To save time and bandwidth, you set imagePullPolicy: Never in your manifest. This tells Kubernetes to skip external registries like Docker Hub and use the version already on your machine. But instead of your app spinning up, the Pod sits in a Waiting state with a 100% failure rate.
The ErrImageNeverPull error means Kubernetes is following your instructions too literally. It is forbidden from pulling the image from the cloud, but it also cannot find that image in the local storage of the specific worker node where the Pod was scheduled. If the image isn't exactly where the Kubelet expects it, the deployment hits a dead end.
Is This Your Problem?Start by checking your pod status to confirm the error. Run the following command:
kubectl get pods
If the STATUS column shows ErrImageNeverPull, you need to look at the internal event log. Use describe to see exactly what the Kubelet is complaining about:
kubectl describe pod <pod-name>
Scroll down to the Events section. You will likely see a warning like this:
Warning Failed 2s (x2 over 5s) kubelet Failed to pull image "myapp:latest": rpc error: code = Unknown desc = failed to pull and unpack image: ErrImageNeverPull
This confirms the node searched its local cache, found nothing, and was blocked from looking elsewhere by your configuration.
Common Root Causes- The Node Mismatch: In a 3-node cluster, you might have built the image on node-1, but Kubernetes scheduled your Pod on node-3. Since node-3 doesn't have the image, the Pod fails.- Local Cluster Isolation: Tools like Minikube and Kind run inside their own virtual machines or Docker containers. Your host machine might have the image, but the internal Kubernetes environment is isolated from your host's Docker storage.- Image Tag Typos: You built myapp:v1.0.1, but your YAML file points to myapp:latest. Even a small version mismatch causes a search failure.- Residual Configs: You accidentally left imagePullPolicy: Never in a manifest meant for a staging or production environment.## How to Fix It### 1. Use IfNotPresent for Better FlexibilityInstead of Never, use IfNotPresent. This tells Kubernetes to use a local image if it exists, but allows it to reach out to a registry if the image is missing. It’s the safest default for most development workflows.
Update your YAML like this:
spec:
containers:
- name: my-container
image: myapp:latest
imagePullPolicy: IfNotPresent
2. Sideload Images into Local ClustersIf you are using Minikube, the cluster cannot see images on your host OS by default. You must manually push the image into Minikube’s internal cache:
minikube image load myapp:latest
For Kind (Kubernetes in Docker) users, use the specific load command to sync your host image with the cluster nodes:
kind load docker-image myapp:latest --name your-cluster-name
3. Build Directly Inside the ClusterYou can skip the "load" step by pointing your terminal's Docker environment directly to the Minikube daemon. Run this command before you build your image:
eval $(minikube docker-env)
docker build -t myapp:latest .
Now, when you build the image, it's created directly inside the Minikube environment. Kubernetes will find it instantly even with the Never policy enabled.
4. Verify Image Presence on the NodeIf you are managing a bare-metal cluster, SSH into the failing node. You need to verify the image actually exists in the runtime's cache. For modern clusters using containerd, use ctr or crictl:
# For Containerd
sudo ctr -n k8s.io images list | grep myapp
# For older Docker runtimes
docker images | grep myapp
Verifying the FixOnce you have moved the image or updated the policy, delete the failing pod so Kubernetes can recreate it:
kubectl delete pod <pod-name>
Monitor the new pod's progress with kubectl get pods -w. When it works, the describe events will show a successful local match:
Normal Pulled 5s kubelet Container image "myapp:latest" already present on machine