Kubernetes ImagePullBackOff and ErrImagePull: How to Fix

Your deployment rolls out, and the pods never start. kubectl get pods shows ErrImagePull, which a moment later becomes ImagePullBackOff. Unlike a crashing app, this failure happens before your code ever runs — Kubernetes can't even get the container image onto the node, so there's nothing to start. The good news: because it's a pull problem, not a runtime problem, the causes are a short and well-understood list, and the fix is usually quick once you read the error.

This guide explains what these two statuses mean, why they happen, and how to diagnose and fix each cause.

What ErrImagePull and ImagePullBackOff Mean

These are two stages of the same problem:

• ErrImagePull is the first failure: the kubelet tried to pull the container image and the pull failed.
• ImagePullBackOff is what comes next: after the failed pull, Kubernetes waits — with an increasing back-off delay — before trying again, exactly like it does for crash loops. So ImagePullBackOff just means "the image pull failed and I'm pausing before retrying."

The key point: the container never started because its image isn't on the node. Whatever's wrong is between the kubelet and the registry — the name, the tag, the credentials, or the network path to it.

The Common Causes

Almost every image-pull failure is one of these:

• Wrong image name or tag. A typo in the repository, or a tag that doesn't exist (myapp:lastest instead of latest, or a version that was never pushed). The single most common cause.
• Image doesn't exist in the registry. The CI build didn't push, the tag was deleted, or you're pointing at the wrong registry entirely.
• Private registry without credentials. The image is private and the pod has no imagePullSecret, so the registry returns 401 Unauthorized / 403 Forbidden.
• Expired or wrong credentials. The imagePullSecret exists but the token has expired or lacks permission for that repository (common with short-lived cloud registry tokens — ECR, GCR, ACR).
• Rate limiting. Public registries throttle anonymous pulls. Docker Hub's pull limits, in particular, surface as failed pulls with a 429 Too Many Requests-style message on busy clusters.
• Network or DNS problems. The node can't reach the registry — a firewall, a DNS resolution failure, or no egress to the registry's endpoint.
• Wrong architecture. The image was built for amd64 but the node is arm64 (or vice versa) and there's no matching manifest.

How to Diagnose It

The error message almost always names the cause — you just have to read it:

1. Describe the pod. kubectl describe pod <name> and read the Events at the bottom. This is where the actual registry error appears, and it's usually unambiguous:
   • manifest unknown / not found → the image or tag doesn't exist (typo or never pushed).
   • 401 Unauthorized / 403 Forbidden / pull access denied → a credentials problem (missing or invalid imagePullSecret).
   • 429 or "toomanyrequests" → registry rate limiting.
   • dial tcp ... i/o timeout / DNS errors → a network path problem reaching the registry.
   • no match for platform → architecture mismatch.
2. Verify the image reference. Copy the exact image: string from your manifest and try to pull it yourself: docker pull <image> from a machine with the right credentials. If it fails for you too, it's the image/name/tag — not Kubernetes.
3. Check the pull secret. Confirm the pod references an imagePullSecret, that the Secret exists in the same namespace, and that it has valid credentials for that registry.
4. Test connectivity from the node. If the error is network-related, check that the node can resolve and reach the registry host.

How to Fix Each Cause

• Wrong name/tag → correct the image: field; double-check the tag actually exists in the registry. Prefer immutable, specific tags over latest to avoid surprises.
• Image not pushed → confirm your CI pipeline built and pushed the tag your manifest references; re-run the push if needed.
• Missing credentials → create an imagePullSecret (kubectl create secret docker-registry ...) and reference it in the pod spec (or attach it to the service account).
• Expired token → refresh the credential; for cloud registries, automate token renewal (e.g. a credential helper) so short-lived tokens don't lapse.
• Rate limiting → authenticate your pulls (authenticated limits are higher), use a pull-through cache or mirror, or host critical images in your own registry.
• Network/DNS → open egress to the registry, fix DNS, or use a registry mirror reachable from the cluster.
• Architecture mismatch → build a multi-arch image (or the right single arch) so a manifest matches the node's platform.

A good habit that prevents most of these: pin specific image tags, authenticate pulls, and verify the image exists in the registry before rolling out — most ImagePullBackOffs are caught in seconds at deploy time rather than discovered in production.

How Webalert Helps

ImagePullBackOff means new pods can't start — which during a rollout can quietly leave you running on old (or too few) pods while you think you've deployed. Outside-in monitoring is what catches the user-facing fallout:

• Uptime and endpoint monitoring that flags when a stuck rollout leaves your service degraded or serving stale versions.
• Deploy-time verification — confirm from outside that the new version is actually live and responding after a release, not silently blocked on a failed image pull.
• Multi-region checks so a rollout that fails to bring up new pods is caught as real user impact, not just an internal event.
• Fast alerting so a failed deploy that can't pull its image doesn't go unnoticed until customers complain.

Kubernetes will keep retrying the pull; Webalert tells you whether your users are getting a working service in the meantime.

Summary

ErrImagePull and ImagePullBackOff mean Kubernetes couldn't pull your container image, so the pod never started — a failure that happens before your code runs and lives entirely between the kubelet and the registry. The causes are a short list: a wrong name or tag, an image that was never pushed, missing or expired registry credentials, rate limiting, network/DNS problems, or an architecture mismatch.

The fix starts with reading the Events in kubectl describe pod, which names the cause directly — manifest unknown (bad tag), 401/403 (credentials), 429 (rate limit), or a network error. Correct the reference, fix the pull secret, authenticate to dodge rate limits, and pin specific tags so deploys fail loudly at build time instead of silently at runtime. Then verify from the outside that your new version is actually serving traffic.

Confirm every deploy is actually live

Start monitoring with Webalert ->

See features and pricing. No credit card required.