Infra Notes

Kubernetes ImagePullBackOff: fix image name and registry authentication

Fix Kubernetes ImagePullBackOff by reading Pod events, validating the image reference, and checking private-registry credentials in the correct namespace.

Published

KubernetesImagePullBackOffimagePullSecretsContainer Registrykubectl

Problem

A Pod remains in ErrImagePull or ImagePullBackOff. Kubernetes cannot retrieve the configured image and increases the delay between retries. Common causes are a nonexistent tag, incorrect registry path, missing credentials, registry throttling, or node-to-registry network failure.

Quick answer

Start with the exact event message:

bash

kubectl describe pod <pod> -n <namespace>
kubectl get pod <pod> -n <namespace> \
  -o jsonpath='{.spec.containers[*].image}{"\n"}'

Interpret phrases such as not found, unauthorized, denied, manifest unknown, no basic auth credentials, or i/o timeout. Each points to a different layer; recreating the Pod does not correct any of them.

Validate the image reference

Confirm the registry hostname, repository path, tag, and architecture. Prefer an immutable digest or release tag rather than latest:

yaml

image: registry.example.com/platform/api@sha256:<digest>

Verify that the release pipeline actually pushed the referenced artifact. A successful application deployment job does not prove that its preceding image-publish job created the intended tag.

Check private-registry credentials

The imagePullSecret must exist in the same namespace as the Pod:

bash

kubectl get pod <pod> -n <namespace> \
  -o jsonpath='{.spec.imagePullSecrets[*].name}{"\n"}'
kubectl get secret <secret> -n <namespace> \
  -o jsonpath='{.type}{"\n"}'

Expected Secret types are kubernetes.io/dockerconfigjson or the older kubernetes.io/dockercfg. Check whether the Pod inherits the secret from its ServiceAccount:

bash

kubectl get serviceaccount <service-account> -n <namespace> -o yaml

Do not paste the .dockerconfigjson value into a ticket or decode it in CI output. If credentials expired or were rotated, replace them using the organization’s secret-management workflow.

Separate authentication from connectivity

An unauthorized response proves the registry is reachable but rejected the identity. A timeout, DNS error, or TLS error points to node networking, DNS, proxy, firewall, or CA trust instead.

If only Pods scheduled on one node fail, compare node DNS, egress, container runtime, disk pressure, and credential-provider configuration. If every node fails at the same time, inspect the registry and shared identity path.

Prevention

  • Publish images before updating the workload manifest.
  • Use immutable tags or digests.
  • Validate registry access from the same identity path used by cluster nodes.
  • Rotate credentials before expiry and monitor pull failures.
  • Keep image repository and tag values explicit in GitOps changes.

If the image starts but repeatedly exits, follow Kubernetes CrashLoopBackOff debugging instead.

References