How to Fix ImagePullBackOff (Kubernetes)

Quick Answer: ImagePullBackOff means Kubernetes cannot pull a container image from a registry. This is often due to an incorrect image name, tag, or missing authentication. Inspect the pod's events with `kubectl describe pod <pod-name>` to find the specific error.

What Causes This Error

Incorrect image name or tag in the Pod specification.
Image does not exist in the specified registry.
Private registry requires authentication, and credentials are not provided or are incorrect.
Network connectivity issues preventing access to the image registry.
Image registry is down or experiencing problems.

Step-by-Step Fixes

Fix 1: Verify Image Name and Tag

Check the image name and tag in your deployment or pod YAML file. Example: `image: myregistry/myrepo/myimage:v1.0.0`.,Confirm the image and tag exist in your container registry. Use `docker pull myregistry/myrepo/myimage:v1.0.0` locally to test.

Fix 2: Provide Registry Authentication

Create a Docker registry secret: `kubectl create secret docker-registry regcred --docker-server=<your-registry-server> --docker-username=<your-username> --docker-password=<your-password> --docker-email=<your-email>`.,Add the `imagePullSecrets` field to your Pod or Deployment specification: `imagePullSecrets: - name: regcred`.,Apply the updated Pod or Deployment YAML: `kubectl apply -f your-deployment.yaml`.

Fix 3: Check Network Connectivity

From a node in your cluster, attempt to ping or curl the registry URL. Example: `ping your-registry-server` or `curl -v https://your-registry-server/v2/`.,Review firewall rules and network policies that might block outbound connections from your Kubernetes nodes to the image registry.

Fix 4: Inspect Pod Events for Specific Errors

Get the pod name: `kubectl get pods`.,Describe the pod to see detailed events: `kubectl describe pod <pod-name>`. Look for messages like 'Failed to pull image', 'manifest unknown', or 'unauthorized'.

Fix 5: Check Registry Status

Visit the status page for your image registry provider (e.g., Docker Hub status, AWS ECR status, Google Container Registry status).,If using a self-hosted registry, verify the registry service is running and accessible.

Advanced Fixes

Advanced Fix 1: Advanced Fix: Authentication to a Private Registry

Verify your `imagePullSecrets` are correctly configured in the Pod or Deployment manifest. Example: `imagePullSecrets: - name: my-registry-secret`,Ensure the secret exists and is of type `kubernetes.io/dockerconfigjson`. Check with `kubectl get secret my-registry-secret -o yaml`.,Confirm the secret's data (`.dockerconfigjson`) is base64 encoded and contains valid registry credentials. Decode and inspect with `echo <base64-data> | base64 --decode`.

Advanced Fix 2: Advanced Fix: Node-Specific Image Pull Issues

SSH into the affected node(s) where the Pod is scheduled.,Attempt to manually pull the image using Docker or Containerd CLI: `docker pull <image-name>:<tag>` or `sudo crictl pull <image-name>:<tag>` (for Containerd). This can reveal network or authentication issues specific to the node.,Check the container runtime logs on the node for errors. For Docker: `sudo journalctl -u docker.service`. For Containerd: `sudo journalctl -u containerd.service`.

Advanced Fix 3: Advanced Fix: Image Layer Corruption or Disk Space Issues

SSH into the affected node.,Check disk space on the node: `df -h`. Ensure sufficient space is available, especially in `/var/lib/docker` or `/var/lib/containerd`.,If disk space is low, consider cleaning up old images: `docker system prune -a` (use with caution, this removes all unused images, containers, networks, and volumes). For Containerd, use `crictl rmi --prune`.