How to fix ErrImagePull in Kubernetes

KubernetesBEGINNERHIGHUpdated Dec 6, 2025· 190 views

ErrImagePull is the initial failure when Kubernetes cannot pull a container image. It immediately precedes ImagePullBackOff and indicates authentication, network, or image reference problems.

Quick fix

Fixes ErrImagePull

kubectl describe pod <pod-name>
  1. Examine the pod events for error details
  2. Verify the image reference is correct
  3. Check imagePullSecrets configuration
  4. Test registry connectivity from a cluster node
kubernetes — error
kubectl describe pod <pod-name>
ErrImagePull

What this error means

ErrImagePull is the immediate error state when the kubelet fails to pull a container image from a registry. This is distinct from ImagePullBackOff, which represents the retry grace period that follows. Both errors indicate the same underlying issue—the image cannot be retrieved. When you see ErrImagePull, Kubernetes has just attempted a pull and failed. After this initial failure, the status transitions to ImagePullBackOff as Kubernetes waits before retrying. The error details in pod events reveal whether it's an authentication issue, network problem, or missing image.

Typical symptoms

  • Pod status shows ErrImagePull before transitioning to ImagePullBackOff
  • Events show Failed to pull image with specific error details
  • Error messages include manifest unknown or not found
  • Authentication failures show unauthorized or access denied
  • Pod cannot start and remains in pending state
  • Container creation fails at image pull stage
  • Deployment rollout stalls waiting for pods to become ready

Common causes

  1. Container image name or tag is misspelled or does not exist
  2. Registry requires authentication but no imagePullSecrets configured
  3. Credentials in imagePullSecret are expired or incorrect
  4. Network issues prevent nodes from reaching the container registry
  5. Image was deleted or moved to a different registry location
  6. Using latest tag but the image has been updated or removed
  7. Private registry certificate is not trusted by the nodes
  8. Registry is temporarily unavailable or experiencing outages

How to fix "ErrImagePull"

1Examine the pod events for error details

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

bash
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

2Verify the image reference is correct

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

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

Verify the image exists by pulling it locally:

bash
docker pull your-registry/image:tag

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

3Check imagePullSecrets configuration

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

bash
# 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:

bash
kubectl create secret docker-registry myregistry \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<token>
4Test registry connectivity from a cluster node

Launch a debug pod to test network access:

bash
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

5Validate registry credentials

Decode and verify the secret contains correct credentials:

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

Test the credentials work:

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

Recreate the secret if credentials have expired or changed.

6Use image digests instead of tags for reliability

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

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

Get the digest for an image:

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

Digests guarantee you get the exact image version you tested.

Advanced notes

For multi-node clusters, remember that images are pulled per-node. If using imagePullPolicy: IfNotPresent, the image might exist on some nodes but not others, causing inconsistent failures.

With containerd as the runtime (default in newer Kubernetes), registry configuration is handled differently than Docker. Ensure registry mirrors and credentials are configured in containerd's config.toml on each node.

For EKS, nodes need IAM permissions for ECR. For GKE, verify Workload Identity configuration. For AKS, use the built-in ACR integration.

Avoid using the 'latest' tag in production—it causes unpredictable behavior and makes rollbacks difficult. Pin to specific versions or use digests.

Frequently asked questions

What does "ErrImagePull" mean?
ErrImagePull is the immediate error state when the kubelet fails to pull a container image from a registry. This is distinct from ImagePullBackOff, which represents the retry grace period that follows. Both errors indicate the same underlying issue—the image cannot be retrieved.
How do I fix "ErrImagePull"?
ErrImagePull is the initial failure when Kubernetes cannot pull a container image. It immediately precedes ImagePullBackOff and indicates authentication, network, or image reference problems.
What causes "ErrImagePull"?
Container image name or tag is misspelled or does not exist Registry requires authentication but no imagePullSecrets configured Credentials in imagePullSecret are expired or incorrect
Is the "ErrImagePull" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading