Kubernetes "ImagePullBackOff / ErrImagePull" after deploy in CI - Fix it

ErrImagePull is the first failed pull; ImagePullBackOff is the kubelet backing off and retrying. The deploy itself succeeded, but the node cannot fetch the image: a bad tag, a non-existent image, or registry credentials the cluster does not have.

What this error means

After a deploy, kubectl get pods shows ErrImagePull then ImagePullBackOff, and kubectl describe pod reports Failed to pull image ...: ... not found or unauthorized.

Warning  Failed  kubelet  Failed to pull image "registry.example.com/api:v1.4.2":
rpc error: code = NotFound desc = manifest for registry.example.com/api:v1.4.2
not found

Common causes

The tag or image does not exist

The image was never pushed, or the tag the deploy references (a typo, an unbuilt SHA) is not in the registry.

The cluster cannot authenticate to the registry

A private registry needs an imagePullSecret or a node-level credential the cluster does not have, so the pull is unauthorized.

How to fix it

Confirm the exact image reference, then check auth

1. Read kubectl describe pod for the precise registry/repo/tag and the failure reason.
2. Verify the image and tag exist in the registry (build/push completed before deploy).
3. For a private registry, ensure the pod has a working imagePullSecret.

kubectl describe pod <pod> | sed -n '/Events/,$p'

Attach a registry pull secret

Create a docker-registry secret and reference it from the pod or its service account.

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=ci --docker-password="$REG_TOKEN" -n prod

How to prevent it

• Deploy the immutable digest or a tag you just pushed, not a guessed one.
• Verify the push step completed before the deploy step runs.
• Keep imagePullSecrets attached to the deploy service account.

Related guides