Kubernetes "ErrImagePull" - Fix Failed Image Pulls in CI

ErrImagePull is the first failed image-pull attempt, before the kubelet starts backing off. The event line under it carries the real reason - not found, unauthorized, or a network/registry error.

What this error means

A pod briefly shows ErrImagePull (then usually ImagePullBackOff). kubectl describe pod shows a Failed event with the concrete pull error from the kubelet.

Failed to pull image "ghcr.io/acme/api:v1.2.3": rpc error: code = Unknown
desc = failed to pull and unpack image ...: failed to resolve reference: unexpected
status from HEAD request: 403 Forbidden

Common causes

Authentication failure (401/403)

The registry rejected the pull because the pod has no valid credentials for a private image, or the token used is wrong/expired.

Image or tag not found (404)

The reference points at a repository or tag that does not exist - a typo, an un-pushed tag, or a deleted image.

Network/DNS or registry error

The kubelet could not reach the registry - DNS failure, blocked egress, or a registry 5xx. This class is often transient.

How to fix it

Identify the HTTP status in the event

1. Run kubectl describe pod <pod> and read the Failed event.
2. 403/401 → fix imagePullSecrets/credentials.
3. 404 / "not found" / "manifest unknown" → fix the image name or tag.
4. i/o timeout / no such host → registry network or DNS.

Verify the image is pullable from outside the cluster

Pull it directly with the same credentials to confirm the reference and auth before blaming Kubernetes.

docker pull ghcr.io/acme/api:v1.2.3
docker manifest inspect ghcr.io/acme/api:v1.2.3

How to prevent it

• Pin and verify image references in CI before deploying.
• Keep registry credentials current and scoped to the images you pull.
• Mirror critical base images to a registry you control.

Related guides