Kubernetes Troubleshooting

Kubernetes ImagePullBackOff & ErrImagePull Troubleshooting

Learn how to troubleshoot Kubernetes ImagePullBackOff and ErrImagePull errors. Diagnose incorrect image names, missing tags, private registry authentication, imagePullSecrets, DNS and network failures, TLS errors and container runtime problems.

Quick Diagnosis

The fastest way to troubleshoot ImagePullBackOff is to inspect the Pod Events before changing the deployment.

01

Check Pod status

Confirm the Pod is reporting ImagePullBackOff or ErrImagePull and identify the affected container.

kubectl get pod <pod-name> -n <namespace>
02

Describe the Pod

Inspect the Events section for the actual image-pull failure returned by the kubelet or container runtime.

kubectl describe pod <pod-name> -n <namespace>
03

Check the image

Verify the exact registry, repository and tag configured for the container.

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

Check registry access

Determine whether the node can reach the registry and whether authentication is required.

kubectl get pod <pod-name> -o yaml
05

Check imagePullSecrets

For private registries, verify that the correct image pull secret is configured and available in the namespace.

kubectl get secrets -n <namespace>

What Does ImagePullBackOff Mean?

Kubernetes needs to pull the container image from a registry before the container can start. If the image cannot be downloaded, Kubernetes reports an image-pull failure.

ErrImagePull indicates that an image pull attempt failed. ImagePullBackOff indicates that Kubernetes has repeatedly failed to pull the image and is backing off before retrying.

First command to remember:

kubectl describe pod <pod-name> -n <namespace>

Look at the Events section. It normally contains the registry or container-runtime error that explains why the image could not be pulled.

Common Causes of ImagePullBackOff

Incorrect Image Name

The image repository or registry hostname is incorrect, so the container runtime cannot locate the requested image.

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

Invalid or Missing Tag

The specified image tag does not exist in the registry. This commonly happens after a deployment references a newly expected tag that was never pushed.

kubectl describe pod <pod-name>

Private Registry Authentication

The registry requires credentials but the Pod does not have a valid imagePullSecret or equivalent workload identity configuration.

kubectl get pod <pod-name> -o yaml

Image Does Not Exist

The repository or tag may not have been pushed to the registry at all.

kubectl describe pod <pod-name>

Registry Network Problem

The node may be unable to reach the registry because of DNS, firewall, proxy, routing or outbound network restrictions.

kubectl describe pod <pod-name>

Registry Rate Limiting

Public registries may throttle anonymous or high-volume image pulls.

kubectl describe pod <pod-name>

TLS or Certificate Error

The container runtime may reject the registry connection because of certificate or TLS configuration problems.

kubectl describe pod <pod-name>

Container Runtime Problem

The node's container runtime may have its own image-pull, disk, credential or connectivity issue.

kubectl get nodes -o wide

Kubernetes Image Pull Errors to Watch

The exact error message matters. Different registry errors require different fixes.

Failed to pull image "nginx:invalid-tag": manifest unknown

The requested image tag does not exist in the registry.

pull access denied for private-repo/app, repository does not exist or may require authorization

The registry may require authentication or the repository reference may be incorrect.

Back-off pulling image

Kubernetes is backing off and retrying image pulls after repeated failures.

dial tcp: lookup registry.example.com: no such host

The node cannot resolve the registry hostname through DNS.

x509: certificate signed by unknown authority

The node's container runtime does not trust the registry certificate.

kubectl get events -A --sort-by=.lastTimestamp

Real-World ImagePullBackOff Troubleshooting

Scenario 1: Wrong image tag

Start with the Pod events. If the registry reports that the manifest or tag does not exist, verify the deployment image against the image tags actually available in the registry.

1.kubectl get pod <pod-name>
2.kubectl describe pod <pod-name>
3.kubectl get deployment <deployment-name> -o yaml
4.kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'

Scenario 2: Private registry authentication failure

Check whether the workload references the expected imagePullSecret or uses another supported registry authentication mechanism. Verify the secret exists in the same namespace as the Pod.

1.kubectl describe pod <pod-name>
2.kubectl get secret -n <namespace>
3.kubectl get serviceaccount <service-account> -o yaml
4.kubectl get deployment <deployment-name> -o yaml

Scenario 3: Registry DNS or network failure

If events show DNS, timeout or connection errors, investigate node-level DNS, routing, firewall, proxy and outbound network configuration rather than changing the application image.

1.kubectl describe pod <pod-name>
2.kubectl get nodes -o wide
3.kubectl run registry-test --rm -it --image=curlimages/curl -- sh
4.nslookup <registry-hostname>

Scenario 4: Image exists but pull still fails

When the image reference is correct, inspect the detailed runtime error and the affected node. Disk pressure, runtime configuration, certificate trust and registry connectivity can all affect image pulls.

1.kubectl describe pod <pod-name>
2.kubectl get pod <pod-name> -o yaml
3.kubectl get nodes -o wide
4.kubectl describe node <node-name>

Troubleshooting Private Container Registries

Private registries require Kubernetes workloads to authenticate before the node can pull protected images. The authentication method depends on the registry and Kubernetes platform.

Check imagePullSecrets

kubectl get pod <pod-name> -o yaml

Look for the imagePullSecrets configuration in the Pod specification or its associated ServiceAccount.

Verify Secret exists

kubectl get secrets -n <namespace>

The registry credential must be available in the namespace where the workload is running.

Security caution: Never paste registry passwords, decoded Secret values or long-lived credentials into tickets, logs, source code or public documentation.

Verify the Container Image

Before troubleshooting networking or credentials, make sure the workload is requesting the image you actually intended to deploy.

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

Debugging Registry DNS and Network Connectivity

Kubernetes image pulls happen from the node's container runtime. Therefore, connectivity from your laptop does not prove that the Kubernetes node can reach the registry.

Temporary network test

kubectl run registry-test --rm -it --image=curlimages/curl -- sh

From the temporary troubleshooting environment, test DNS and HTTP connectivity to the relevant registry endpoint where appropriate.

Production-Safe Troubleshooting

Image-pull failures can affect application availability, so diagnose the exact failure before changing production configuration.

Start with kubectl get and kubectl describe before changing the workload.

Confirm the exact image registry, repository and tag.

Check the Pod Events section before assuming the application image is broken.

For private registries, verify credentials and imagePullSecrets in the correct namespace.

Do not expose registry passwords or Secret values in tickets, logs or screenshots.

Avoid repeatedly deleting Pods without understanding why the image pull is failing.

Check whether the problem affects one node or multiple nodes.

After correcting the configuration, verify the rollout and Pod readiness.

How to Prevent ImagePullBackOff

Use immutable image tags or digests for production deployments where appropriate.

Validate that images are successfully pushed before deploying a new version.

Use approved private registries for production workloads.

Configure registry authentication through supported Kubernetes mechanisms.

Monitor registry availability and authentication failures.

Keep node DNS and outbound connectivity healthy.

Monitor node disk pressure and container runtime health.

Avoid relying on mutable tags such as latest for controlled production releases.

Related Kubernetes Guides

kubectl Commands Cheat Sheet

Use the complete kubectl reference for Pods, deployments, logs, events, nodes and troubleshooting.

Read guide →

Pending Pods Troubleshooting

Troubleshoot Pods that cannot be scheduled because of resources, taints, affinity, storage or node constraints.

Read guide →

CrashLoopBackOff Troubleshooting

Investigate containers that start but repeatedly terminate and restart.

Read guide →

ImagePullBackOff FAQ

What does ImagePullBackOff mean in Kubernetes?+

ImagePullBackOff means Kubernetes was unable to pull a container image and is backing off before retrying. The underlying reason is normally visible in the Pod Events section returned by kubectl describe pod.

What is the difference between ErrImagePull and ImagePullBackOff?+

ErrImagePull indicates that Kubernetes encountered an error while attempting to pull the image. ImagePullBackOff indicates that the pull has repeatedly failed and Kubernetes is delaying subsequent retry attempts.

How do I find the image that Kubernetes is trying to pull?+

You can inspect the Pod specification with kubectl get pod <pod-name> -o yaml or use a JSONPath expression such as kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].image}'.

How do I fix ImagePullBackOff for a private Docker registry?+

First verify the image name and tag. Then verify that the required registry credentials are available through the supported authentication mechanism, such as an imagePullSecret, and that the credential is accessible in the Pod's namespace.

Why does an image pull work on my laptop but fail in Kubernetes?+

Your laptop and Kubernetes nodes may have different network access, DNS configuration, registry credentials, certificate trust or proxy settings. Kubernetes pulls images from the node environment, not from your local workstation.

Should I use latest in production Kubernetes deployments?+

Using mutable tags such as latest makes deployments harder to reproduce because the tag can point to different image content over time. Controlled release processes commonly use versioned tags and, where appropriate, immutable image digests.

This Kubernetes ImagePullBackOff troubleshooting guide is intended for Kubernetes administrators, DevOps engineers, SREs and production support teams. Always verify commands and registry configuration against your Kubernetes platform and environment before making production changes.