ImagePullBackOff errors in Kubernetes - Commands & Configuration

Introduction

Sometimes, Kubernetes cannot download the container image needed to run your app. This causes an ImagePullBackOff error, which means Kubernetes keeps trying but fails to get the image. This stops your app from starting.

When your pod fails to start and shows ImagePullBackOff status.

When you update your deployment with a new image but Kubernetes cannot find it.

When you use a private container registry and Kubernetes lacks permission to pull images.

When the image name or tag is mistyped in your pod or deployment configuration.

When network issues prevent Kubernetes from reaching the container registry.

Commands

Check the status of all pods to see which ones have ImagePullBackOff errors.

Terminal

kubectl get pods

Expected Output

NAME           READY   STATUS             RESTARTS   AGE

my-app-pod     0/1     ImagePullBackOff   0          2m

Get detailed information about the pod to find why the image pull failed.

Terminal

kubectl describe pod my-app-pod

Expected Output

Name:         my-app-pod

Namespace:    default

Status:       Pending

Containers:

  my-app:

    Image:      myregistry.example.com/my-app:latest

    State:      Waiting

      Reason:   ImagePullBackOff

Events:

  Type     Reason          Age   From               Message

  ----     ------          ----  ----               -------

  Warning  Failed          2m    kubelet, node-1    Failed to pull image "myregistry.example.com/my-app:latest": rpc error: code = Unknown desc = Error response from daemon: pull access denied for myregistry.example.com/my-app, repository does not exist or may require 'docker login'

  Warning  BackOff         1m    kubelet, node-1    Back-off pulling image "myregistry.example.com/my-app:latest"

Check if the image pull secret for private registry access exists and is configured.

Terminal

kubectl get secret regcred -o yaml

Expected Output

apiVersion: v1

data:

  .dockerconfigjson: eyJhdXRocyI6eyJteXJlZ2lzdHJ5LmV4YW1wbGUuY29tIjp7InVzZXJuYW1lIjoiZXhhbXBsZSIsInBhc3N3b3JkIjoiZXhhbXBsZXBhc3MiLCJhdXRoIjoiZXhhbXBsZWF1dGgiLCJlbWFpbCI6ImV4YW1wbGVAZXhhbXBsZS5jb20ifX19

kind: Secret

metadata:

  name: regcred

  namespace: default

type: kubernetes.io/dockerconfigjson

Add the image pull secret to the default service account so pods can use it to pull images from the private registry.

Terminal

kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}'

Expected Output

serviceaccount/default patched

Delete the pod to force Kubernetes to recreate it and try pulling the image again with the correct settings.

Terminal

kubectl delete pod my-app-pod

Expected Output

pod "my-app-pod" deleted

Key Concept

If you remember nothing else from this pattern, remember: ImagePullBackOff means Kubernetes cannot download your container image, usually due to wrong image name, missing permissions, or network issues.

Common Mistakes

Using a wrong image name or tag in the pod spec.

Kubernetes cannot find the image in the registry, so it fails to pull it.

Double-check the image name and tag for typos and confirm the image exists in the registry.

Not creating or attaching the correct image pull secret for private registries.

Kubernetes lacks permission to access the private registry, so image pull fails.

Create a docker-registry secret with 'kubectl create secret docker-registry' and attach it to the pod or service account.

Ignoring network or firewall issues blocking access to the container registry.

Kubernetes nodes cannot reach the registry, so image pull times out or fails.

Ensure network connectivity and firewall rules allow access to the registry endpoints.

Summary

Use 'kubectl get pods' to identify pods with ImagePullBackOff status.

Use 'kubectl describe pod' to see detailed error messages about image pull failures.

Check and configure image pull secrets for private registries to grant Kubernetes access.

Delete the failing pod to let Kubernetes retry pulling the image with corrected settings.