Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Kubernetes pod stuck in ErrImagePull or ImagePullBackOff

ErrorErrImagePull

Short answer

The kubelet could not pull the container image. Run kubectl describe pod and read the Events: they give the registry's reason. The common causes are a wrong image name or tag, a private registry with no imagePullSecrets, or a pull secret that lives in another namespace than the pod.

  • Applies to Kubernetes 1.34, kubectl 1.34
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Describe the pod and read the Events at the bottom. The registry's own message says whether the image is missing or access is denied.

    kubectl describe pod <pod-name> -n <namespace>
  2. 2Match what you see, then jump to its fix

    1. 1Events show the image or tag cannot be foundThe image name or tag is wrong, or the image was never pushedFix
    2. 2Events show the registry refusing access, and docker pull works only after docker loginThe registry is private and the pod has no imagePullSecretsFix
    3. 3A secret is configured, yet the same pull error repeats in one namespace onlyThe pull secret exists, but in a different namespaceFix

What does the error look like?

  • ErrImagePull
  • ImagePullBackOff

Cause 1 of 3

The image name or tag is wrong, or the image was never pushed

1Check

Kubernetes lists a wrong image name, an image not pushed to the registry, and a manual pull test as the first things to check. Pull the exact string from the manifest by hand.

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

2Fix

Correct the name or tag in the manifest, or push the missing image. Without a tag, Kubernetes assumes latest, so write the tag out.

containers:
  - name: app
    image: registry.example.com/team/app:1.4.2

3Verify

Apply the manifest and watch the pod become Running.

kubectl apply -f deployment.yaml
kubectl get pods -n <namespace> -w

Confirmed by kubernetes.io

Did this fix it?

Cause 2 of 3

The registry is private and the pod has no imagePullSecrets

1Check

ImagePullBackOff covers pulling from a private registry without an imagePullSecret. Only pods that provide their own keys can use the private registry.

kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.imagePullSecrets}'

2Fix

Create a docker-registry secret in the pod's namespace and reference it under imagePullSecrets.

kubectl create secret docker-registry regcred -n <namespace> \
  --docker-server=<registry-server> \
  --docker-username=<user> \
  --docker-password=<password>

# pod spec
spec:
  imagePullSecrets:
    - name: regcred

3Verify

Restart the workload and check that the pod starts.

kubectl get pods -n <namespace>

Confirmed by kubernetes.io

Did this fix it?

Cause 3 of 3

The pull secret exists, but in a different namespace

1Check

imagePullSecrets must be Secrets in the same namespace as the pod, and each namespace needs its own copy.

kubectl get secret regcred -n <namespace>

2Fix

Create the secret in the pod's namespace, or add it to the namespace's ServiceAccount so new pods get it automatically.

kubectl create secret docker-registry regcred -n <namespace> \
  --docker-server=<registry-server> \
  --docker-username=<user> \
  --docker-password=<password>

3Verify

The secret is found in the namespace.

kubectl get secret regcred -n <namespace>

Confirmed by kubernetes.io

Did this fix it?

How do I stop it coming back?

  • Pin images to a version tag or digest instead of latest.
  • Pull each image by hand with the same string before you deploy it.
  • Create the pull secret in every namespace as part of the namespace setup.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.