How to fix ImagePullBackOff in Kubernetes

Get detailed information about the pull failure:

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.

Test pulling the image from a machine with registry access:

docker pull <image>:<tag>

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

image: gcr.io/project-id/image-name:tag
# or
image: 123456789.dkr.ecr.us-east-1.amazonaws.com/repo:tag

Create a Docker registry secret:

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:

spec:
  imagePullSecrets:
    - name: regcred

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

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:

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.

Test connectivity from a node or debug pod:

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.

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

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.