How to Fix Kubernetes ImagePullBackOff

Q: How do I see why an image pull is failing?

Run `kubectl describe pod ` and read the Events - the message tells you exactly: 'manifest not found' (bad tag), 'pull access denied' (private/wrong name), or a timeout (network).

ImagePullBackOff means Kubernetes tried to pull your container image and failed, so it's backing off and retrying. The cause is almost always a bad image reference or missing registry credentials. Here's how to find which.

Kubernetes Engineerkuberneteskubectlimages

What ImagePullBackOff means

The pod can't start because the image pull failed. BackOff just means Kubernetes is waiting longer between retries. The real reason is in the pod's events - the image name is wrong, the tag doesn't exist, or the registry needs credentials you didn't supply.

Step 1: read the events - they name the exact cause

kubectl describe pod <pod>

Look at the Events at the bottom. The message is specific:

Failed to pull image "busybox:9.99": ... manifest for busybox:9.99 not found

That's a non-existent tag. Other messages map to other causes (below).

The common causes

Event message	Cause	Fix
`manifest ... not found` / `not found: tag`	Tag doesn't exist (typo, e.g. `:9.99`)	Use a real tag (`busybox:1.36`)
`repository does not exist` / `pull access denied`	Wrong image name, or private repo	Fix the name; add an imagePullSecret
`unauthorized` / `authentication required`	Private registry, no credentials	Create + reference an `imagePullSecret`
`dial tcp ... timeout`	Node can't reach the registry	Network/DNS/firewall to the registry
`ErrImagePull` then `ImagePullBackOff`	First pull failed, now retrying	Fix the underlying message above

Step 2: fix the image reference and re-apply

Most often it's a wrong tag or name in the manifest:

containers:
  - name: web
    image: busybox:1.36     # was busybox:9.99 (no such tag)

kubectl apply -f deployment.yaml
kubectl rollout status deployment/web --timeout=90s

Private registries

If the image is private, the pull needs credentials:

kubectl create secret docker-registry regcred \
  --docker-server=<registry> --docker-username=<u> --docker-password=<p>

Then reference it under spec.imagePullSecrets in the pod template.

Want to try it hands-on? HeyDevJob gives you this exact setup in a live cloud workspace in your browser - edit it, run it, and see it work. Free, nothing to install.

Try it in a workspace →

What you'll practice

Reading kubectl describe events to identify the pull failure
Correcting a bad image tag/name and re-applying
Adding an imagePullSecret for a private registry

FAQ

What causes ImagePullBackOff in Kubernetes?

Kubernetes can't pull the image - usually a non-existent tag or misspelled image name, a private registry without an imagePullSecret, or the node can't reach the registry. kubectl describe pod names the exact reason in its Events.

How do I see why an image pull is failing?

Run kubectl describe pod <pod> and read the Events - the message tells you exactly: 'manifest not found' (bad tag), 'pull access denied' (private/wrong name), or a timeout (network).

What's the difference between ErrImagePull and ImagePullBackOff?

ErrImagePull is the first failed attempt; ImagePullBackOff is Kubernetes backing off and retrying that failed pull. Both have the same root cause - fix the image reference or credentials.

Keep learning

Fix a Kubernetes CrashLoopBackOffKubernetes project Heal a Kubernetes Service With No EndpointsKubernetes project Schedule a Pending Kubernetes PodKubernetes project Kubernetes roadmapStep by step to hired Kubernetes interview questionsSTAR answers All Kubernetes projectsProjects hub

Learn it by doing. Open this in a live cloud workspace, make the change yourself, and keep a record of the work you can share.

Open the workspace →