How to fix ErrImagePull in Kubernetes

Get the specific error message that explains why the pull failed:

kubectl describe pod <pod-name>

In the Events section, look for messages containing "Failed to pull image". Common messages include:
- "manifest unknown" - image or tag doesn't exist
- "unauthorized" - authentication required
- "connection refused" - network issue

Check your pod or deployment spec for the exact image reference:

kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'

Verify the image exists by pulling it locally:

docker pull your-registry/image:tag

Ensure the registry URL, image name, and tag are all correct.

Verify a pull secret exists and is referenced in the pod:

# List secrets in the namespace
kubectl get secrets

# Check if pod references the secret
kubectl get pod <pod-name> -o jsonpath='{.spec.imagePullSecrets}'

If missing, create the secret and update your deployment:

kubectl create secret docker-registry myregistry \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<token>

Launch a debug pod to test network access:

kubectl run debug --rm -it --image=curlimages/curl -- sh

# Test registry access
curl -v https://your-registry.com/v2/

If this fails, check:
- DNS resolution for the registry hostname
- Firewall rules allowing outbound HTTPS
- Network policies that might block egress

Decode and verify the secret contains correct credentials:

kubectl get secret myregistry -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

Test the credentials work:

docker login <registry> -u <username> -p <password>
docker pull <image>

Recreate the secret if credentials have expired or changed.

Tags can be moved or deleted. For production, consider using immutable digests:

image: myregistry/myapp@sha256:abc123def456...

Get the digest for an image:

docker inspect --format='{{index .RepoDigests 0}}' myimage:tag

Digests guarantee you get the exact image version you tested.