K8s Image Pull Error

A Kubernetes Pod fails to start because the kubelet cannot pull the specified container image from a registry.

Common Causes

Incorrect image name, tag, or repository path.
Missing or invalid authentication credentials for a private image registry.
The specified image tag does not exist in the registry.
Network connectivity issues preventing access to the registry (e.g., Docker Hub rate limits, firewall).

How to Fix

1 Check Pod Events and Describe

Use `kubectl describe pod` to get detailed error messages from the kubelet, which often specifies the exact cause (e.g., 'not found', 'unauthorized').

BASH

$ kubectl describe pod <pod-name> -n <namespace>

2 Verify Image Name and Tag

Manually check that the image name, tag, and repository path in your Pod spec or Deployment are correct and exist.

BASH

$ docker pull <full-image-name:tag>

3 Configure Image Pull Secrets

If using a private registry, ensure a Secret with credentials exists and is referenced correctly in the Pod spec or ServiceAccount.

BASH

 $ # Create the secret
kubectl create secret docker-registry my-registry-key \
  --docker-server=<registry-url> \
  --docker-username=<user> \
  --docker-password=<pass> \
  --docker-email=<email>

# Reference it in a Pod spec
# spec:
#   imagePullSecrets:
#   - name: my-registry-key

4 Check Node Network and Docker Config

Log into the affected node and test basic network connectivity to the registry and Docker daemon configuration.

BASH

 $ # On the Kubernetes node
ping <registry-host>
curl -v https://<registry-host>/v2/
systemctl status docker