k8s Flashcards
← Back to blog
ImagePullBackOffTroubleshootingkubectlCKAD

ImagePullBackOff: When Kubernetes Cannot Pull Your Image

ErrImagePull and ImagePullBackOff mean the kubelet never got your container image — not that your app crashed. How to diagnose tag, registry, and secret issues fast.

2 min read

You deploy. The Pod never reaches Running.

kubectl get pods -n prod
api-x7   0/1   ImagePullBackOff   0

kubectl describe pod api-x7 -n prod shows:

Warning  Failed  kubelet  Error: ErrImagePull
Warning  Failed  kubelet  rpc error: code = NotFound desc = manifest unknown: v2.1

The container never started. There is nothing useful in kubectl logs yet — the image is the blocker.

ImagePullBackOff vs ErrImagePull

StatusMeaning
**ErrImagePull**Latest pull attempt failed
**ImagePullBackOff**Kubelet backs off between retries

Both point to the same class of problem: registry, tag, auth, or network — not application code.

Common causes

1. Wrong tag or typo

manifest unknown almost always means the tag does not exist in that registry. Check:

kubectl get deploy api -n prod -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Compare with your registry UI or docker pull / crictl pull from a test machine.

2. Private registry without pull secret

Symptoms: 401 Unauthorized or pull access denied. Fix:

kubectl get pod api-x7 -n prod -o jsonpath='{.spec.imagePullSecrets}'
kubectl create secret docker-registry regcred ...
kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"regcred"}]}'

Or set imagePullSecrets on the Pod template.

3. ImagePullPolicy: Never

If the tag exists only locally on one node and policy is Never, other nodes fail. Usually you want IfNotPresent or Always with a real registry.

4. Registry rate limits or outage

Docker Hub anonymous limits, regional outages, or DNS failures show as timeout errors in Events — not manifest unknown.

First-step workflow

  1. kubectl describe pod — read Events for the exact registry error
  2. Verify image string in Deployment/StatefulSet spec
  3. Test pull from a node (crictl pull) if you have SSH access
  4. Check pull secrets and ServiceAccount wiring

Do not delete the Pod repeatedly hoping the tag appears — fix the image reference or registry access.

Exam angle (CKAD)

Examiners love wrong tags and missing imagePullSecrets. Your first move is describe + read Events, then fix the manifest — not restart the kubelet.

Practice ImagePull-style decisions in Pod Debugging (free) and CKAD Exam Prep.