ErrImagePull: The first failed attempt to pull a container image

ErrImagePull is the immediate result of a failed image pull. If the failure repeats, the status becomes ImagePullBackOff. The two have the same causes and the same fixes.

Applies to: All Kubernetes versions, any container runtime

What it means

ErrImagePull appears the moment the kubelet's first pull attempt fails. It is short-lived: after further failures the kubelet begins delaying retries and the status changes to ImagePullBackOff. Seeing ErrImagePull rather than ImagePullBackOff tells you only that the failure is recent, not that it is a different problem. Diagnose it exactly as you would ImagePullBackOff: the useful information is in the pod's events, not in the status string.

Most common causes

• A wrong image name, tag, or registry hostname.
• Missing or invalid registry credentials for a private image.
• Registry rate limiting.
• The node has no network route or DNS resolution to the registry.
• The image manifest does not include the node's CPU architecture.

How to diagnose it

1. Run kubectl describe pod POD and read the event message, which contains the registry's own error text.
2. Verify the image reference resolves from a machine that can reach the registry.
3. Check that any referenced pull secret exists in the same namespace as the pod.

How to fix it

1. Correct the image reference, or add valid imagePullSecrets in the pod's namespace.
2. Authenticate to the registry if you are being rate limited anonymously.
3. Resolve node-level network or DNS problems if the registry is unreachable.

Notes

Because the status flips to ImagePullBackOff quickly, most people only ever see the back-off form. There is no separate fix for this state.

Related

• ImagePullBackOff — Repeated pull failures, now with a back-off delay

Sources

• Kubernetes documentation — Images
• Kubernetes documentation — Debug Pods