🚨 Kubernetes Error Guide: 'ErrImagePull' First-Attempt Image Pull Failure

Exact Error Message

ErrImagePull is the status Kubernetes shows the moment the kubelet’s first attempt to pull a container image fails. You will see it in the pod status:

NAME                       READY   STATUS         RESTARTS   AGE
web-6d8c9f7b5c-q4n2t       0/1     ErrImagePull   0          12s

And in the pod’s events from kubectl describe pod:

Events:
  Type     Reason     Age   From     Message
  ----     ------     ----  ----     -------
  Normal   Scheduled  13s   default  Successfully assigned prod/web-6d8c9f7b5c-q4n2t to node-2
  Normal   Pulling    12s   kubelet  Pulling image "registry.example.com/web:v2.3.1"
  Warning  Failed     10s   kubelet  Failed to pull image "registry.example.com/web:v2.3.1": rpc error: code = NotFound desc = failed to pull and unpack image: failed to resolve reference: not found
  Warning  Failed     10s   kubelet  Error: ErrImagePull

A common variant is the authorization failure on a private image:

  Warning  Failed  8s  kubelet  Failed to pull image "registry.example.com/web:v2.3.1": failed to authorize: 401 Unauthorized
  Warning  Failed  8s  kubelet  Error: ErrImagePull

What the Error Means

ErrImagePull means the kubelet asked the container runtime to fetch the image and that single attempt failed. It is the immediate failure state — the pull was just tried and it did not work.

This is the key distinction from ImagePullBackOff: ErrImagePull is the fresh failure, while ImagePullBackOff is what you see after the kubelet has failed several times and started backing off its retries (10s, 20s, 40s, doubling up to a 5-minute cap). In practice a pod flickers from ErrImagePull to ImagePullBackOff within the first minute as retries accumulate. They share every root cause — ErrImagePull is simply the earlier, less-retried view of the same problem. Because the container never starts, the pod stays 0/1 with RESTARTS = 0 and kubectl logs returns nothing.

Common Causes

• Wrong image name or repository. A typo in the repo (web-api instead of web) resolves to a reference the registry does not have, returning not found.
• Nonexistent tag. The repository is correct but the tag (v2.3.1) was never pushed, or CI referenced it before publishing, yielding manifest unknown.
• Registry unreachable or DNS failure. The node cannot route to the registry (dial tcp ... connection timed out) or cannot resolve its hostname (no such host).
• Missing imagePullSecret. A private image pulled anonymously returns 401 Unauthorized because no credentials are attached.
• Expired or invalid credentials. A secret exists but its token has expired or is wrong, so the registry returns 403 Forbidden: access denied.

How to Reproduce the Error

Deploy a pod that references a tag that does not exist in a real registry:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: prod
spec:
  replicas: 1
  selector:
    matchLabels: { app: web }
  template:
    metadata:
      labels: { app: web }
    spec:
      containers:
        - name: web
          image: registry.example.com/web:v9.9.9-does-not-exist

kubectl apply -f web.yaml
kubectl get pods -l app=web -w

Within seconds the pod reports ErrImagePull, then transitions to ImagePullBackOff once the kubelet begins backing off.

Diagnostic Commands

# Confirm the status and the exact image string
kubectl get pods -l app=web -o wide
kubectl get pod web-6d8c9f7b5c-q4n2t -o jsonpath='{.spec.containers[0].image}'

# Read the pull failure message from events
kubectl describe pod web-6d8c9f7b5c-q4n2t | grep -A12 Events
kubectl get events --field-selector involvedObject.name=web-6d8c9f7b5c-q4n2t \
  --sort-by='.lastTimestamp'

# Check whether a pull secret is attached
kubectl get pod web-6d8c9f7b5c-q4n2t -o jsonpath='{.spec.imagePullSecrets}'

# Verify the repo and tag actually exist in the registry
crane ls registry.example.com/web
crane manifest registry.example.com/web:v2.3.1 >/dev/null && echo OK || echo MISSING

# Test DNS and connectivity from the affected node
kubectl debug node/node-2 -it --image=busybox -- nslookup registry.example.com
kubectl debug node/node-2 -it --image=busybox -- wget -qO- https://registry.example.com/v2/

Step-by-Step Resolution

1. Read the event message first. The wording in Failed to pull image classifies the cause: not found / manifest unknown (name or tag), 401 / 403 (auth), dial tcp / no such host (network or DNS).

2. For not found or manifest unknown, compare the image string against the registry. Fix the repository name or push the missing tag, then re-apply:

   kubectl set image deployment/web web=registry.example.com/web:v2.3.2 -n prod

3. For 401 / 403, check for and create a registry secret:

   kubectl create secret docker-registry regcred \
     --docker-server=registry.example.com \
     --docker-username=ci --docker-password=$REGISTRY_TOKEN -n prod
   kubectl patch serviceaccount default -n prod \
     -p '{"imagePullSecrets":[{"name":"regcred"}]}'

4. For network or DNS errors, fix the registry hostname, firewall path, or node resolver, or point the pod at an in-cluster mirror.

5. Restart the rollout so a fresh pull runs immediately instead of waiting out the backoff window:

   kubectl rollout restart deployment web -n prod

Prevention and Best Practices

• Pin images by immutable digest (@sha256:...) or an explicit tag, never latest, so the referenced image cannot disappear underneath a deploy.
• Attach imagePullSecrets to the namespace ServiceAccount, not individual pods, so every workload inherits valid credentials.
• Verify the tag exists in the registry during CI before any deploy references it.
• Rotate registry credentials with automation and alert before expiry; an expired token turns every new pod into an ErrImagePull.
• Validate that new nodes can resolve and reach the registry during node bootstrap, especially in air-gapped clusters. See more in Kubernetes & Helm guides.

Related Errors

• Kubernetes Error: ImagePullBackOff / ErrImagePull Image Pull Failures — the combined guide covering the backoff state that follows repeated ErrImagePull attempts.
• Kubernetes Error: Failed to pull image (CRI / containerd) — the deeper containerd-level view of manifest, auth, and rate-limit failures.

Frequently Asked Questions

What is the difference between ErrImagePull and ImagePullBackOff? ErrImagePull is the immediate failure of a single pull attempt. ImagePullBackOff is what the kubelet reports after several failed attempts, when it has started waiting (backing off) between retries. Same root causes, different retry stage.

Why does my pod show ErrImagePull but RESTARTS stays 0? The container image never reached the node, so no container was ever created. There is nothing to restart — the failure is in the pull phase, before the container runs.

How do I see the real reason behind ErrImagePull? Run kubectl describe pod <pod> and read the Failed to pull image event. Its text (not found, 401, toomanyrequests, no such host) tells you whether it is a naming, auth, rate-limit, or network problem.

Can ErrImagePull be caused by the wrong architecture? Yes — if the image has no manifest for the node’s platform (e.g. no linux/amd64), the pull fails. That CRI-level case is covered in the Failed to pull image guide.

Does deleting the pod fix ErrImagePull? Only if the underlying cause was transient (a brief registry outage). For a bad name, missing tag, or missing secret, deleting just re-runs the same failing pull. Fix the root cause first, then kubectl rollout restart.