Fix Kubernetes ErrImagePull: Diagnose Pull Failures (2026)

The ErrImagePull error means the Kubelet on your node tried to pull a container image but failed, and it can’t start the pod.

1. Image Name or Tag Typo

Diagnosis: kubectl describe pod <pod-name> -n <namespace> Look for the Image field under Containers. Is it spelled correctly? Is the tag correct?

Fix: Correct the image name or tag in your pod definition (Deployment, Pod, StatefulSet, etc.) and re-apply. For example, change nginx:latest to nginx:1.21.6.

Why it works: The Kubelet is asking the container registry for an image that doesn’t exist, so the registry correctly refuses the request.

2. ImagePullSecrets Not Configured (Private Registry)

Diagnosis:

kubectl get pods -n <namespace> (check if the pod is stuck in ImagePullBackOff or ErrImagePull)
kubectl describe pod <pod-name> -n <namespace> (look for ImagePullBackOff status and events)
kubectl get secret <your-secret-name> -n <namespace> (check if the secret exists)
kubectl get serviceaccount <your-service-account-name> -n <namespace> -o yaml (check if imagePullSecrets is listed under secrets)

Fix:

Create an ImagePullSecret:

kubectl create secret docker-registry regcred \
  --docker-server=<your-registry-server> \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  --docker-email=<your-email> \
  -n <namespace>

If your pod uses a specific Service Account, edit it to include the secret:

kubectl edit serviceaccount <your-service-account-name> -n <namespace>

Add or ensure imagePullSecrets is present:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: default
  namespace: <namespace>
secrets:
- name: regcred # <-- This is your ImagePullSecret name
imagePullSecrets:
- name: regcred # <-- This is your ImagePullSecret name

If your pod definition directly specifies imagePullSecrets, add it there instead:

apiVersion: v1
kind: Pod
metadata:
  name: my-private-pod
  namespace: <namespace>
spec:
  containers:
  - name: my-container
    image: <your-private-image>:<tag>
  imagePullSecrets:
  - name: regcred # <-- This is your ImagePullSecret name

Then delete the failing pod (kubectl delete pod <pod-name> -n <namespace>) and let the controller recreate it.

Why it works: Kubernetes needs credentials to authenticate with private container registries. The ImagePullSecret stores these credentials, and the Service Account or Pod definition tells the Kubelet which credentials to use.

3. Insufficient Permissions on Registry

Diagnosis:

kubectl describe pod <pod-name> -n <namespace> (check events for authentication/authorization errors, e.g., "unauthorized", "access denied")
Log in to your container registry manually using the credentials from your ImagePullSecret (if applicable) from a machine outside the Kubernetes cluster. If you can’t pull the image there, the credentials are bad or the user doesn’t have access to that specific image.

Fix: Update the credentials in your ImagePullSecret or grant the user account associated with the credentials the necessary read permissions for the image in your container registry.

Why it works: Even with correct credentials, the user account might not have permission to access the specific image or repository.

4. Network Connectivity Issues to Registry

Diagnosis:

kubectl describe pod <pod-name> -n <namespace> (look for timeouts or connection refused errors in events).
SSH into the node where the pod is scheduled (find the node name from kubectl get pods -o wide -n <namespace>).
Try to pull the image manually from the node: docker pull <image-name>:<tag> or crictl pull <image-name>:<tag> (depending on your container runtime).
Check firewall rules on the node and any network policies within Kubernetes (kubectl get networkpolicy -n <namespace>).

Fix: Ensure the node has network access to the container registry. This might involve:

Opening outbound firewall ports (usually 443 for HTTPS).
Configuring http_proxy or https_proxy environment variables for the container runtime if your cluster uses a proxy.
Adjusting Kubernetes NetworkPolicy objects to allow egress traffic to the registry’s IP address or domain.

Why it works: The Kubelet cannot reach the registry to download the image if network paths are blocked or misconfigured.

5. Registry Unreachable or Down

Diagnosis:

kubectl describe pod <pod-name> -n <namespace> (look for connection timeouts).
Try accessing the registry’s web interface or using docker login from an external machine.
Check the status page of your container registry provider (e.g., Docker Hub, GCR, ECR, Quay.io).

Fix: Wait for the registry service to become available. If it’s a private registry, investigate and resolve the issue with the registry’s infrastructure.

Why it works: The Kubelet can’t download an image from a registry that isn’t responding.

6. Corrupted Image Cache on Node

Diagnosis:

kubectl describe pod <pod-name> -n <namespace> (might show generic pull errors).
SSH into the node where the pod is scheduled.
List images on the node: docker images or crictl images. Look for the image in question.
If the image is present but suspected of corruption, you might need to remove it: docker rmi <image-id> or crictl rmi <image-id>. Caution: This will affect other pods on the node that might be using the same image.

Fix: Remove the potentially corrupted image from the node’s local cache and let Kubernetes re-pull it. Delete the pod (kubectl delete pod <pod-name> -n <namespace>) to force a re-pull.

Why it works: Sometimes, an image pull can be interrupted or corrupted on the node itself, leading to subsequent failures even if the registry is fine. Forcing a re-pull fetches a fresh copy.

7. Disk Space Full on Node

Diagnosis:

kubectl describe pod <pod-name> -n <namespace> (look for errors related to I/O, disk space, or writing the image).
SSH into the node where the pod is scheduled.
Check disk usage: df -h. Pay attention to the partition where container images are stored (often /var/lib/docker or similar).

Fix: Free up disk space on the node. This might involve:

Removing old, unused images: docker image prune -a or crictl rmi --prune.
Deleting old containers: docker container prune.
Removing unused volumes or logs.
Increasing the disk size of the node.

Why it works: The container runtime cannot write the image layers to disk if there’s no free space available.

The next error you might hit is CrashLoopBackOff if the image pulls successfully but the container immediately exits.