How to Fix Kubernetes ImagePullBackOff Error

In this tutorial, you'll learn about How to Fix Kubernetes ImagePullBackOff Error. We cover key concepts, practical examples, and best practices.

The Problem

You deploy a pod and it stays in ImagePullBackOff:

NAME                     READY   STATUS             RESTARTS   AGE
my-pod-6b4c9f8d7-abc12   0/1     ImagePullBackOff   0          2m

Describing the pod shows:

Failed to pull image "my-app:latest": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/my-app:latest": not found

The pod cannot pull the container image because it does not exist, the tag is wrong, or the registry requires authentication.

Quick Fix

Step 1: Describe the pod for details

kubectl describe pod my-pod-6b4c9f8d7-abc12

Look for the Events section at the bottom. It shows the exact pull error.

Step 2: Fix the image name or tag

# Check the current image
kubectl get pod my-pod-6b4c9f8d7-abc12 -o jsonpath='{.spec.containers[0].image}'

# Edit the deployment to fix the image
kubectl edit deployment my-deployment

Change image: my-app:latest to image: username/my-app:1.0.0.

Step 3: Add registry credentials

For private registries, create a pull secret:

kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=your-username \
  --docker-password=your-password \
  --docker-email=your-email

Add it to your pod spec:

spec:
  imagePullSecrets:
  - name: regcred

Step 4: Verify the fix

kubectl get pods -w

Expected output:

my-pod-6b4c9f8d7-abc12   0/1     Pulling    0     5s
my-pod-6b4c9f8d7-abc12   1/1     Running    0     10s

Alternative Solutions

If you are on Minikube, build the image inside the cluster:

eval $(minikube docker-env)
docker build -t my-app:latest .

Or set imagePullPolicy: Never for local images.

Use kubectl describe for Detailed Diagnostics

kubectl describe pod <pod-name>
# Events:
#   Type     Reason     Age   From     Message
#   ----     ------     ----  ----     -------
#   Warning  BackOff    5m    kubelet  Back-off restarting failed container

The Events section at the bottom of kubectl describe output is the most valuable diagnostic tool. It shows a chronological log of scheduling failures, image pull errors, and container crashes.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Always use explicit image tags, never latest in production.
• Store registry credentials as Kubernetes secrets before deploying.
• Test image pulling locally with docker pull before deploying.