How to Fix Kubernetes ImagePullBackOff

When a Kubernetes Pod enters the ImagePullBackOff state, it indicates that Kubernetes attempted to pull a container image for one of your Pod’s containers, but something went wrong—so Kubernetes is backing off and retrying. This problem typically means that the image cannot be downloaded from the specified container registry. Below, we’ll look at what it is, why it happens, and how to fix it.

What Is ImagePullBackOff?

ImagePullBackOff is a Kubernetes Pod status indicating that Kubernetes attempted to pull a container image but failed, and is now backing off and retrying with increasingly longer intervals.

Common Causes of ImagePullBackOff

1. Typo or Mistyped Image Name

If you have a minor typo in your image path or tag, Kubernetes won’t find it.

e.g. myrepo/myapp:lates instead of myrepo/myapp:latest.

Sample Pod Spec with a Typo in the Image Tag

Suppose you have the following Pod specification (pod.yaml) that includes a misspelled image tag:

apiVersion: v1
kind: Pod
metadata:
  name: imagepullbackoff-example
  labels:
    app: demo
spec:
  containers:
  - name: myapp-container
    # Note the typo "lates" instead of "latest"
    image: myrepo/myapp:lates
    imagePullPolicy: IfNotPresent

In this YAML:

• The image is set to myrepo/myapp:lates instead of myrepo/myapp:latest.
• This will cause Kubernetes to fail to pull the correct image, leading to ErrImagePull followed by ImagePullBackOff if the error persists.

Checking Pod Events

After applying the Pod manifest, you can run the following command to see its status and events:

kubectl describe pod imagepullbackoff-example

Below is a typical error snippet you might see in the Events section:

Events:
  Type     Reason          Age    From               Message
  ----     ------          ----   ----               -------
  Normal   Scheduled       10s    default-scheduler  Successfully assigned default/imagepullbackoff-example to minikube
  Normal   Pulling         9s     kubelet            Pulling image "myrepo/myapp:lates"
  Warning  Failed          8s     kubelet            Failed to pull image "myrepo/myapp:lates": 
                                rpc error: code = NotFound desc = failed to pull and unpack image 
                                "myrepo/myapp:lates": no match for platform in manifest
  Warning  Failed          8s     kubelet            Error: ErrImagePull
  Normal   BackOff         7s     kubelet            Back-off pulling image "myrepo/myapp:lates"
  Warning  Failed          7s     kubelet            Error: ImagePullBackOff

Key points from the snippet:

• Pulling image "myrepo/myapp:lates" indicates the Pod tried to pull the misspelled tag lates.
• Error: ErrImagePull appears when the pull first fails.
• Error: ImagePullBackOff means Kubernetes is now “backing off” and retrying with exponential delays.

2. Private Registry Without Proper Credentials

When your image is hosted on a private registry (e.g., a private Docker registry or Amazon ECR), you need to provide valid pull secrets. Without them, Kubernetes cannot authenticate and pull the image.

Example of a Private Registry Credentials Issue

Another common cause is when you reference a private image without proper credentials. Below is a minimal Pod spec that references a non-public registry without providing the necessary pull secret:

apiVersion: v1
kind: Pod
metadata:
  name: private-registry-example
spec:
  containers:
  - name: private-app
    image: myprivate-registry.com/org/private-app:1.0
    imagePullPolicy: IfNotPresent

If you don’t have a corresponding imagePullSecrets entry in your spec or if your secret is invalid, you’ll see errors similar to:

Events:
  Type     Reason          Age    From               Message
  ----     ------          ----   ----               -------
  Normal   Scheduled       15s    default-scheduler  Successfully assigned default/private-registry-example to minikube
  Normal   Pulling         14s    kubelet            Pulling image "myprivate-registry.com/org/private-app:1.0"
  Warning  Failed          13s    kubelet            Failed to pull image "myprivate-registry.com/org/private-app:1.0":
                                rpc error: code = Unknown desc = Error response from daemon:
                                pull access denied for myprivate-registry.com/org/private-app, repository does not exist 
                                or may require 'docker login': denied: requested access to the resource is denied
  Warning  Failed          13s    kubelet            Error: ErrImagePull
  Normal   BackOff         12s    kubelet            Back-off pulling image "myprivate-registry.com/org/private-app:1.0"
  Warning  Failed          12s    kubelet            Error: ImagePullBackOff

The key phrase here is pull access denied, which often indicates you need proper authentication to pull from that registry.

3. Exceeded Rate Limits

Exceeded rate limits occur when a registry, such as Docker Hub, imposes a cap on the number of image pulls allowed within a specific timeframe, causing subsequent pull attempts to fail.

For example, you might see an error toomanyrequests: You have reached your pull rate limit in the Pod events after running kubectl describe pod <pod-name>.

This happens if unauthenticated or free-tier authenticated pulls exceed daily or hourly pull quotas.

To fix it, you can authenticate with Docker Hub credentials (allowing higher pull quotas), mirror your images in a private or self-hosted registry, or reduce the frequency of Pod restarts that trigger image pulls.

The Docker Hub plan limits will take effect on March 1, 2025. No charges on Docker Hub pulls or storage will be incurred between December 10, 2024, and February 28, 2025. Click Here for more details.

4. Network issues or DNS problems

Network issues or DNS problems can prevent a Kubernetes node from reaching the container image registry, leading to pull failures and ultimately resulting in the ImagePullBackOff status. Common scenarios include misconfigured proxies, firewalls, or security groups that block outbound traffic to the registry’s domain or IP, causing timeouts or connection errors.

Additionally, if the node’s DNS settings are incorrect, or there is an internal DNS server malfunction, the node may be unable to resolve the registry’s hostname. For example, if you see repeated failed pull attempts with an “unknown host” or “connection timeout” message in the Pod events, it indicates that the node can’t reach or resolve the registry endpoint.

How to Fix These Issues

Correct the Image Name/Tag

Verify the correct repository name and tag in your YAML manifest—especially spelling, punctuation, and the exact tag (e.g., :latest, :stable, or a semantic version). After correcting the YAML (e.g., changing lates to latest or adding the missing version tag), you can apply the updated manifest. Kubernetes will then attempt to pull the correct image, clearing the ImagePullBackOff error if the rest of your configuration is valid.

In the first example, simply fix the typo mistake image: myrepo/myapp:lates to image: myrepo/myapp:latest.

Use a Pull Secret for Private Registries:

To pull images from a private registry, you must provide Kubernetes with valid credentials via a pull secret. First, create a Docker registry secret with the necessary credentials, for example:

kubectl create secret docker-registry myregistrykey \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-server=<registry-url> \
  --namespace <namespace>

This command generates a secret named myregistrykey in the specified namespace. Next, reference this secret in your Pod or Deployment specification:

spec:
  imagePullSecrets:
    - name: myregistrykey

By including the imagePullSecrets field, Kubernetes can use your registry credentials to successfully pull private images, resolving any ImagePullBackOff errors caused by authentication failures.

ImagePullBackOff is one of the most common errors when running containers in Kubernetes. It almost always boils down to:

• An incorrect image name or tag.
• Missing credentials for a private registry.
• Networking or permissions issues that prevent image pulls.

By carefully checking the Pod events, verifying your image references, and ensuring your cluster can pull images (with correct authentication and network access), you can typically resolve the ImagePullBackOff error and get your workloads running again.