Error: ImagePullBackOff

The “ImagePullBackOff” error means Kubernetes cannot pull the container image. Each attempt fails and the kubelet retries with increasing delays.

What It Means

Kubernetes sent a pull request to the container registry, but the image could not be downloaded. The pod status shows ImagePullBackOff and the container never starts. Common causes range from a typo in the image name to missing registry credentials.

Why It Happens

• The image tag doesn’t exist in the registry (typo or wrong version).
• The image is in a private registry without proper imagePullSecrets.
• The image name or tag is misspelled in the deployment manifest.
• The node doesn’t have network access to the registry.
• Docker Hub rate limits are exceeded for anonymous pulls.
• The registry requires authentication and the secret is missing or expired.
• The image was deleted from the registry.

How to Fix It

Step 1: Check the pod events

kubectl describe pod <pod-name>

Look in the Events section for the exact pull error. Common messages:

• 404 Not Found — image doesn’t exist
• Unauthorized — no credentials for private registry
• context deadline exceeded — network issue
• toomanyrequests — Docker Hub rate limit

Step 2: Verify the image name and tag

kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}'

Compare this against the registry. Test the pull locally:

docker pull <image-name>:<tag>

If this fails with the same error, the image or tag is wrong.

Step 3: Add imagePullSecrets for private registries

Create a Docker registry secret:

kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=<username> \
  --docker-password=<token> \
  --docker-email=<email>

Reference it in your pod spec:

spec:
  imagePullSecrets:
  - name: regcred
  containers:
  - name: app
    image: my-private-image:latest

Step 4: Handle Docker Hub rate limits

Docker Hub limits anonymous pulls to 100 per 6 hours and authenticated pulls to 200 per 6 hours. If you hit a rate limit:

1. Add a Docker Hub secret as shown above.
2. Or use a mirror registry.

Step 5: Check node network access

Verify the node can reach the registry:

kubectl exec -n kube-system <any-pod> -- curl -I https://registry-1.docker.io

If the node is behind a proxy, configure the container runtime to use it.