About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
A pod showing ErrImagePull or ImagePullBackOff is scheduled on a node, but the kubelet could not download its container image. ErrImagePull is the failed attempt. ImagePullBackOff is the kubelet waiting before it tries again, with a delay that grows up to 5 minutes. The reason is in the pod's events: read them with kubectl describe pod, then correct the image name or tag, the pull secret, or the route to the registry.
What the status means
The Kubernetes Images page says ImagePullBackOff "means that a container could not start because Kubernetes could not pull a container image (for reasons such as invalid image name, or pulling from a private registry without imagePullSecret). The BackOff part indicates that Kubernetes will keep trying to pull the image, with an increasing back-off delay." It adds that the delay rises "until it reaches a compiled-in limit, which is 300 seconds (5 minutes)."
The kubelet source code (Kubernetes v1.37.2) shows how the two names relate. The event texts below come from that source code, not from the documentation. After a pull fails, the kubelet records the failure as an event with the text Failed to pull image "<image>": <error>, and the status is ErrImagePull. <image> is the image reference and <error> is the runtime's error text. While the delay is still running, a new attempt does not contact the registry. The kubelet writes the event Back-off pulling image "<image>" and the status is ImagePullBackOff. The earlier pull error is carried along in the container's waiting message.
The source defines related statuses that look similar: InvalidImageName when the image reference cannot be parsed, and ErrImageNeverPull when the pull policy is Never and the image is absent on the node.
The words the registry or runtime uses to explain a refusal are not defined by Kubernetes. The OCI Distribution Specification lists registry error codes such as MANIFEST_UNKNOWN ("manifest unknown to registry"), NAME_UNKNOWN ("repository name not known to registry"), UNAUTHORIZED ("authentication required") and DENIED ("requested access to the resource is denied"). A registry may also send its own text.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| Wrong image name or tag | Event text names a missing repository or manifest | The image string in the pod spec; the tag exists in the registry |
| Private registry, no pull secret | An authentication or access-denied reason | The pod has no imagePullSecrets |
| Secret exists in another namespace | Event FailedToRetrieveImagePullSecret |
The secret is not in the pod's namespace |
| Secret has the wrong credentials | An authentication reason although a secret is set | A manual pull with the same credentials fails |
| Registry or network unreachable | A connection or timeout reason | A manual pull from a node-like host fails or hangs |
| Registry rate limit | A too-many-requests reason | The reason text says too many requests; the OCI Distribution Specification code for it is TOOMANYREQUESTS, "too many requests" |
Pull policy Never |
ErrImageNeverPull |
imagePullPolicy in the pod spec |
Prove the cause before changing anything
All of these are read-only. Replace the names with your own.
1. See the status and the pod name.
kubectl get pods --namespace shop
The Pod Lifecycle page says a Waiting container comes with a reason that summarises why. Note the pod name.
2. Read the events. The Debug Pods page says to run kubectl describe pods and look at the state of the containers and recent events:
kubectl describe pods/web-5d9c8b6f7-k2x9p --namespace shop
kubectl events --for pod/web-5d9c8b6f7-k2x9p --types=Warning --namespace shop
A good result is a Pulling image event followed by a success. kubectl describe lists events of every type. In this case it shows Failed to pull image with the reason text, and Back-off pulling image. The kubelet source code records Failed to pull image as a Warning event and Pulling image and Back-off pulling image as Normal events, so the --types=Warning listing shows only Failed to pull image. Copy the full reason text. It decides which row of the table applies.
3. Read the exact image and any pull secret in the pod.
kubectl get pod web-5d9c8b6f7-k2x9p --namespace shop -o jsonpath='{.spec.containers[*].image}{"\n"}'
kubectl get pod web-5d9c8b6f7-k2x9p --namespace shop -o jsonpath='{.spec.imagePullSecrets[0].name}{"\n"}'
The Images page says that without a tag Kubernetes assumes latest, and without a registry host it assumes Docker's public registry. An empty second output means the pod has no pull secret.
4. Does the secret exist in the same namespace? The Pull an Image page says the secret must exist "in the right namespace", the namespace where the pod is defined:
kubectl get secret regcred --namespace shop
5. Try the pull by hand. The Debug Pods page lists the checks for a waiting pod: the image name is right, the image was pushed to the registry, and a manual pull works, for example docker pull <image> on a workstation. Use the same image string and credentials:
docker pull registry.example.com/team/web:1.4.2
Fix
The image name or tag is wrong
First print the container name and the image the Deployment uses now, and keep both:
kubectl get deployment web --namespace shop -o jsonpath='{.spec.template.spec.containers[*].name}{"\n"}{.spec.template.spec.containers[*].image}{"\n"}'
Disruptive step: the next command changes the pod template, which starts a new rollout and replaces the pods of this Deployment.
Use the container name from the Deployment and the corrected image. kubectl set image takes CONTAINER_NAME_1=CONTAINER_IMAGE_1 pairs, here one pair:
kubectl set image deployment/web web=registry.example.com/team/web:1.4.2 --namespace shop
To undo it: set the container back to the image you printed.
kubectl set image deployment/web web=<image-you-printed> --namespace shop
The pod needs credentials for a private registry
The Pull an Image page creates a secret of type kubernetes.io/dockerconfigjson. It says that if you use a Docker credentials store you will see credsStore instead of an auth entry, and you can create the secret directly, with the page's command-line method, kubectl create secret docker-registry. The steps below show the file method; with a credentials store that file does not carry the credentials, so the page's direct method is the one for that case, as described after the create command below.
First check whether the name is already taken, and save what the cluster answers. The expected answer is a not-found error:
kubectl get secret regcred --namespace shop > /root/regcred-before-2026-11-22.txt 2>&1
cat /root/regcred-before-2026-11-22.txt
If the file shows a secret named regcred instead of a not-found error, stop. That secret was there before you, and pods may use it. Choose another name, run the save again for the new name to a file named for it, use the new name in every command below, including the file name in the undo, and do not delete a secret you did not create.
Risk: the next command stores the registry credentials in the cluster as a Secret. For the command-line method the page also warns, "Typing secrets on the command line may store them in your shell history unprotected", and the file used below holds the same credentials, so keep it private.
If your config.json contains credsStore, do not run the command below; use the page's kubectl create secret docker-registry command instead. The save, the name check, the Risk and the undo apply the same way.
Otherwise, create it from your existing Docker configuration file (the path is an example):
kubectl create secret generic regcred --from-file=.dockerconfigjson=/home/admin/.docker/config.json --type=kubernetes.io/dockerconfigjson --namespace shop
To undo it: first read the file you saved before the create. Delete the secret only if that file shows a not-found error, which proves the secret did not exist before and that this step created it. If it showed a secret, do not delete anything.
cat /root/regcred-before-2026-11-22.txt
kubectl get secret regcred --namespace shop
Only when the saved file shows not found, and the get above shows the secret you created, delete that one secret:
kubectl delete secret regcred --namespace shop
The pod spec field that names the secret is imagePullSecrets. To use the secret, the Deployment's pod template must carry it. First save the Deployment as it is now, and list its revisions. Note the highest revision number in the list, here called N: it is the revision that matches the saved file.
kubectl get deployment web --namespace shop -o yaml > /root/web-deployment-2026-11-22.yaml
kubectl rollout history deployment/web --namespace shop
Preview the change on the server:
kubectl patch deployment web --namespace shop --dry-run=server -p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
Disruptive step: the next command changes the pod template, which starts a new rollout and replaces the pods of this Deployment.
Add the secret to the Deployment:
kubectl patch deployment web --namespace shop -p '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'
To undo it: roll back to revision N, the one whose template matches the saved file. Preview first. Use the number you noted, in place of <N>:
kubectl rollout undo --dry-run=server deployment/web --namespace shop --to-revision=<N>
kubectl rollout undo deployment/web --namespace shop --to-revision=<N>
kubectl get deployment web --namespace shop -o yaml afterwards should show the same pod template as the saved file.
The registry cannot be reached
If the manual pull from a comparable host also fails, the fault is the network, the registry name or the registry itself, not the pod. Fix that first. "Kubernetes Networking Faults: CNI, Services, CoreDNS and How to Trace a Packet" covers cluster networking, and "Docker toomanyrequests: You have reached your pull rate limit" covers a registry that is refusing pulls.
Example (illustrative): in namespace shop, Deployment web uses registry.example.com/team/web:1.4.2. The pod web-5d9c8b6f7-k2x9p shows ErrImagePull, then ImagePullBackOff. kubectl describe shows Failed to pull image with an authentication reason, then Back-off pulling image. The second jsonpath command prints nothing, and kubectl get secret regcred --namespace shop returns not found. The engineer creates regcred in shop, patches the Deployment with imagePullSecrets, and the new pod pulls the image.
Confirm the fix
kubectl get pods --namespace shopshows the new podRunning, notImagePullBackOff.kubectl events --for pod/<name> --namespace shopshowsSuccessfully pulled imageafterPulling image.kubectl rollout status deployment/web --namespace shopreports the rollout complete.- An older pod that was
Pendingor failing has been replaced.
What to watch afterwards
- Pin images to a specific tag or digest. The Images page advises avoiding
:latestin production. - Create pull secrets in every namespace that needs them.
- Watch image pulls after registry certificate or credential changes.
- Check registry credentials before they expire, and put the date in your records.
Read next
Related articles you may want next.
- TroubleshootingDocker toomanyrequests: You have reached your pull rate limitDocker toomanyrequests: You have reached your pull rate limit. Read your limit headers, sign in, cut repeat pulls or add a cache. Check the current page.Read article
- TroubleshootingKubernetes Networking Faults: CNI, Services, CoreDNS and How to Trace a PacketSeparate DNS from Services, Services from the pod network, then capture packets at each hop to prove where a Kubernetes connection stops.Read article
- TroubleshootingDocker "x509: certificate signed by unknown authority" on pull or login to a private registrydocker pull fails with 'x509: certificate signed by unknown authority'? Test the registry with openssl, then add the CA to certs.d or fix its chain.Read article
Risks and limits
- These commands have not been run or lab-tested.
- Event wording is from the kubelet source code at Kubernetes v1.37.2. Other releases may differ.
- Registry error text varies by registry. The OCI codes above are the specification's list, not a promise about what any registry prints.
- A rollback with
kubectl rollout undoalso reverts any other change made to the Deployment after your patch. - Static Pods cannot reference a Secret or a service account, according to the Images page.
Sources
- Images — Kubernetes documentation, last modified February 14, 2026, accessed 22 November 2026
- Pull an Image from a Private Registry — Kubernetes documentation, last modified May 13, 2026, accessed 22 November 2026
- Debug Pods — Kubernetes documentation, last modified August 24, 2026, accessed 22 November 2026
- Pod Lifecycle — Kubernetes documentation, last modified September 27, 2026, accessed 22 November 2026
- kubectl describe — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl events — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl set image — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl patch — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl delete — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl rollout undo — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl rollout status — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- kubectl JSONPath support — Kubernetes documentation, last modified April 06, 2025, accessed 22 November 2026
- types.go and image_manager.go (kubelet images package) — Kubernetes source code, release tag v1.37.2, no date shown, accessed 22 November 2026
- kubectl rollout history — Kubernetes documentation, last modified August 26, 2026, accessed 22 November 2026
- OCI Distribution Specification — Open Container Initiative, release tag v1.1.1, no date shown, accessed 22 November 2026
This article was originally published on .