ImagePullBackOff (or ErrImagePull) means Kubernetes or Docker can’t download the container image. It tried, failed, and is now backing off before retrying.

What causes this error

1. Image doesn’t exist — typo in the image name or tag
2. Private registry without credentials — the registry requires authentication
3. Wrong tag — the specific tag (e.g., v1.2.3) doesn’t exist
4. Registry is down — Docker Hub, ECR, or your private registry is unreachable

Fix 1: Verify the image exists

# Check if the image exists on Docker Hub
docker pull myimage:mytag

# Check a private registry
docker pull registry.example.com/myimage:mytag

# List available tags
# Docker Hub: https://hub.docker.com/r/library/nginx/tags
# Or use: skopeo list-tags docker://nginx

Fix 2: Fix registry credentials (Kubernetes)

# Create a secret for your private registry
kubectl create secret docker-registry my-registry-secret \
  --docker-server=registry.example.com \
  --docker-username=myuser \
  --docker-password=mypassword

# Reference it in your pod spec
# spec:
#   imagePullSecrets:
#     - name: my-registry-secret

Fix 3: Check the image name and tag

# ❌ Common mistakes
image: myapp:latest    # 'latest' might not exist
image: myapp           # missing tag entirely
image: my-app:v1.2.3   # hyphen vs underscore

# ✅ Use the exact image:tag
image: myregistry.com/myapp:v1.2.3

Fix 4: Check network connectivity

# From inside the cluster
kubectl run test --image=busybox --rm -it -- wget -qO- https://registry-1.docker.io/v2/

# Check if your node can reach the registry
curl -I https://registry.example.com/v2/

How to debug

# See the exact error message
kubectl describe pod my-pod | grep -A5 "Events"

# Common messages:
# "manifest unknown" → image or tag doesn't exist
# "unauthorized" → need registry credentials
# "timeout" → network issue

Related: Kubernetes kubectl cheat sheet · Kubernetes: CrashLoopBackOff fix · Docker cheat sheet · Docker vs Kubernetes · What is Kubernetes