How to fix ImagePullBackOff in Kubernetes

KubernetesBEGINNERHIGHUpdated Dec 6, 2025· 310 views

ImagePullBackOff occurs when Kubernetes cannot pull a container image from a registry. The kubelet retries with exponential backoff while you resolve authentication, network, or image reference issues.

Quick fix

Fixes ImagePullBackOff

kubectl describe pod <pod-name>
  1. Check pod events for the specific error
  2. Verify the image exists and is accessible
  3. Create or verify imagePullSecrets for private registries
  4. Check for Docker Hub rate limiting
kubernetes — error
kubectl describe pod <pod-name>
ImagePullBackOff

What this error means

ImagePullBackOff is a pod status indicating that Kubernetes failed to pull a container image and is retrying with increasing delays. After an initial ErrImagePull error, the kubelet enters a backoff state with delays growing from 5 seconds up to 5 minutes between attempts. This error typically stems from one of three categories: the image doesn't exist (wrong name, tag, or registry), authentication is failing (missing or invalid credentials for private registries), or network issues prevent reaching the registry. The specific cause is revealed in the pod events.

Typical symptoms

  • Pod status shows ImagePullBackOff or ErrImagePull
  • Pod remains in Pending state and never starts
  • Events show Back-off pulling image with increasing delays
  • Error messages include repository does not exist or pull access denied
  • Authentication errors show 401 Unauthorized or 403 Forbidden
  • Network errors show connection refused or timeout messages
  • Deployments cannot progress past container creation phase

Common causes

  1. Image name or tag contains a typo or does not exist in the registry
  2. Missing imagePullSecrets for private container registry authentication
  3. Expired or invalid registry credentials in the Kubernetes secret
  4. Docker Hub rate limiting for unauthenticated or free-tier pulls
  5. Network connectivity issues between nodes and the container registry
  6. Firewall rules blocking outbound access to registry endpoints
  7. Image was deleted from the registry after deployment was created
  8. DNS resolution failures preventing registry hostname lookup

How to fix "ImagePullBackOff"

1Check pod events for the specific error

Get detailed information about the pull failure:

bash
kubectl describe pod <pod-name>

Look at the Events section for messages like "unauthorized", "not found", "manifest unknown", or network errors. This tells you which category of problem you're dealing with.

2Verify the image exists and is accessible

Test pulling the image from a machine with registry access:

bash
docker pull <image>:<tag>

Check for typos in your pod spec. Verify the exact image path including registry prefix if not using Docker Hub:

yaml
image: gcr.io/project-id/image-name:tag
# or
image: 123456789.dkr.ecr.us-east-1.amazonaws.com/repo:tag
3Create or verify imagePullSecrets for private registries

Create a Docker registry secret:

bash
kubectl create secret docker-registry regcred \
  --docker-server=<registry-url> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email>

Reference it in your pod spec:

yaml
spec:
  imagePullSecrets:
    - name: regcred

Secrets are namespace-scoped—create them in each namespace that needs them.

4Check for Docker Hub rate limiting

Docker Hub limits pulls for unauthenticated users (100 per 6 hours) and free accounts (200 per 6 hours). Events will show "toomanyrequests" errors.

Authenticate to Docker Hub even for public images:

bash
kubectl create secret docker-registry dockerhub \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=<dockerhub-username> \
  --docker-password=<dockerhub-token>

Consider mirroring frequently-used images to your own registry.

5Verify network connectivity to the registry

Test connectivity from a node or debug pod:

bash
kubectl run debug --rm -it --image=busybox -- /bin/sh
# Inside the pod:
nslookup gcr.io
wget -O- https://gcr.io/v2/

Check that firewall rules and network policies allow outbound HTTPS (port 443) to registry endpoints.

6Delete and recreate the pod to retry immediately

If you've fixed the underlying issue, delete the pod to trigger an immediate retry instead of waiting for backoff:

bash
kubectl delete pod <pod-name>

For deployments, the ReplicaSet will create a new pod automatically. For stuck pods older than 60 minutes, deleting also clears stale events.

Advanced notes

On EKS, use IAM Roles for Service Accounts (IRSA) for ECR authentication instead of static credentials. The node IAM role needs ecr:GetAuthorizationToken and ecr:BatchGetImage permissions.

For GKE with Artifact Registry or Container Registry, use Workload Identity to authenticate. Verify the service account has the artifactregistry.reader role.

In AKS, integrate directly with Azure Container Registry using managed identity—this eliminates the need for imagePullSecrets entirely.

For air-gapped or restricted environments, consider running a local registry mirror or using image caching solutions. Large images may also timeout during pull; increase the kubelet's image-pull-progress-deadline if needed.

Frequently asked questions

What does "ImagePullBackOff" mean?
ImagePullBackOff is a pod status indicating that Kubernetes failed to pull a container image and is retrying with increasing delays. After an initial ErrImagePull error, the kubelet enters a backoff state with delays growing from 5 seconds up to 5 minutes between attempts. This error typically stems from one of three categories: the image doesn't exist (wrong name, tag, or registry), authentication is failing (missing or invalid credentials for private registries), or network issues prevent reaching the registry.
How do I fix "ImagePullBackOff"?
ImagePullBackOff occurs when Kubernetes cannot pull a container image from a registry. The kubelet retries with exponential backoff while you resolve authentication, network, or image reference issues.
What causes "ImagePullBackOff"?
Image name or tag contains a typo or does not exist in the registry Missing imagePullSecrets for private container registry authentication Expired or invalid registry credentials in the Kubernetes secret
Is the "ImagePullBackOff" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading