Kubernetes ImagePullBackOff causes and fixes

TL;DR

ImagePullBackOff means the kubelet cannot download the container image. The three usual causes are a typo in the image name or tag, a missing or wrong imagePullSecret for a private registry, or the tag no longer existing in the registry. Check the exact error on the pod events, then fix the image reference or the registry credentials.

Error / query

Kubernetes ImagePullBackOff causes and fixes

Use this skill when

• A pod shows ImagePullBackOff or ErrImagePull in kubectl get pods
• A new deployment never starts any containers
• kubectl describe pod shows Failed to pull image events
• A previously working deployment breaks after a tag or registry change

Not for this skill when

• The image pulls fine but the container crashes (that is CrashLoopBackOff, a different skill)
• The pod is Pending with no pull events (check scheduling, affinity, resources)
• You are pushing an image and getting registry errors (push-side auth, not pull)
• The failure is a slow pull timing out on a huge image (network/storage, not auth or naming)

Steps

Step 1: Read the exact pull error from the pod events

kubectl describe pod [pod-name] -n [namespace] | grep -A 5 "Failed"

Expected: a concrete message such as repository [name] not found, unauthorized: authentication required, or manifest unknown. The fix depends on which one you see.

Step 2: Verify the image reference actually exists in the registry

kubectl get pod [pod-name] -n [namespace] -o jsonpath='{.spec.containers[*].image}'

Expected: the full image string the pod is trying to pull. Compare it character by character with what is in the registry; typos in the repo name or tag are the most common cause.

Step 3: Check whether the pod has an imagePullSecret for private registries

kubectl get pod [pod-name] -n [namespace] -o jsonpath='{.spec.imagePullSecrets}'
kubectl get secrets -n [namespace]

Expected: if the registry is private and imagePullSecrets is empty or names a secret that does not exist, that is the cause. Create a docker-registry secret and reference it.

Step 4: Create or fix the registry secret

kubectl create secret docker-registry [secret-name] -n [namespace] \
  --docker-server=[registry-host] \
  --docker-username=[username] \
  --docker-password value [registry-token]

Expected: secret created. Then add imagePullSecrets: [{name: [secret-name]}] to the pod spec or attach it to the service account, and the pull succeeds on the next attempt.

Step 5: Force a fresh pull attempt

kubectl delete pod [pod-name] -n [namespace]

Expected: the replacement pod pulls the image again. If the error persists with the same message, the image reference or credentials are still wrong, go back to steps 2-3.

Variant phrasings

"ErrImagePull kubernetes"

The transient state before the backoff kicks in. Same diagnosis; the describe output has the real error.

"unauthorized authentication required pulling image"

Registry credentials are missing, expired, or scoped to the wrong repository. Regenerate the token and update the secret.

"image not found in registry but it exists"

Usually a tag mismatch (e.g. latest vs a pinned tag) or the image living in a different repo path. Verify with the exact string from step 2.

Why it happens

The kubelet asks the registry for a manifest matching the image reference. If the name or tag does not resolve, or the registry rejects the request for missing credentials, the pull fails and the kubelet backs off retrying. The pod never starts because there is nothing to run. It is a reference or auth problem, never an application problem.

Edge cases and pitfalls

• Rate limits on public registries (e.g. Docker Hub anonymous pulls) surface as pull failures; authenticate or use a pull-through cache.
• imagePullPolicy: Always with a mutable latest tag can break a working deploy when the tag moves; pin tags for stability.
• Secrets must live in the same namespace as the pod; a secret in the wrong namespace silently does nothing.
• Private registries with self-signed certs fail pulls at the TLS layer; the error mentions certificate verification, fix the CA trust on the nodes.
• Some registries return manifest unknown for a repo the credentials cannot see, which looks like a typo; verify with a manual pull using the same credentials.

Provenance

Resolved from the public thread: https://vectle.com/posts/pster5OSbL4T0wZzAoQtsygQ