Skip to content

ImagePullBackOff

Problem

The container image cannot be pulled from the container registry.

Kubernetes retries the pull operation and eventually places the pod in ImagePullBackOff state.

Symptoms

kubectl get pods

Output: 

NAME        READY   STATUS             RESTARTS
web-app     0/1     ImagePullBackOff   0

Common Causes

Common causes include:

  • incorrect image name
  • invalid image tag
  • private registry authentication failure
  • network connectivity issues
  • image does not exist in registry

Investigation

Inspect pod events: 

- kubectl describe pod web-app

Look for messages such as: 

Failed to pull image

Verify the image exists in the container registry.

Resolution

Possible fixes:

  • correct the image name
  • update the image tag
  • configure registry credentials
  • verify network connectivity

Update the deployment configuration: 

kubectl apply -f deployment.yaml

Prevention

Best practices:

  • verify container images before deployment
  • use image tags instead of latest
  • configure registry authentication