Kubernetes — ImagePullBackOff

Diagnose ImagePullBackOff from pod events and registry authentication, covering wrong tags, missing pull secrets, architecture mismatches, and rate limits.

intermediatedebuggingkubernetescontainers

Symptoms

kubectl get pods shows ImagePullBackOff or ErrImagePull
The pod stays in Pending and never starts its container
Events mention unauthorized, manifest unknown, or no matching manifest
The same image works on a developer machine but not in the cluster

Possible causes

The image tag does not exist or was overwritten with a different architecture
The pod lacks an imagePullSecret for a private registry
The node architecture does not match the image manifest
The registry is rate-limiting anonymous pulls
The image name or registry host is misspelled in the deployment

Diagnosis steps

Read the pod events

kubectl describe pod POD -n NAMESPACE | sed -n '/Events:/,$p'

Interpretation

The event shows whether the registry returned unauthorized, manifest unknown, or a network error.

Verify the image and its platforms

docker buildx imagetools inspect IMAGE:TAG

Interpretation

A missing tag or a single-architecture manifest explains the failure, especially across arm64/amd64 nodes.

Check pull secrets and service account wiring

kubectl get pod POD -o jsonpath='{.spec.imagePullSecrets}' && kubectl get secret -n NAMESPACE

Interpretation

A private registry requires a referenced secret with valid credentials in the same namespace.

Root cause

The kubelet could not pull the image. The cause is a missing or wrong image reference, missing registry credentials, an architecture mismatch, or registry rate limiting.

Fix

Correct the image reference and tag, attach a valid imagePullSecret to the pod service account, publish a multi-arch manifest, or authenticate the registry. Do not use imagePullPolicy: Always as a substitute for fixing a bad tag.

Risk note

Embedding registry credentials directly in a deployment manifest exposes them to anyone who can read the workload. Use a secret and a dedicated service account.

Verify the fix

Confirm the pod transitions to Running and Ready, the image digest matches the expected build, and a fresh pod can pull after deleting the cached image. Check events for a successful pull.

The event names the failure class

ImagePullBackOff means the kubelet tried to pull the image and failed repeatedly. kubectl describe pod shows the exact error: unauthorized points to credentials, manifest unknown to a missing tag, and no matching manifest to an architecture mismatch. Fix the class, not the symptom.

kubectl describe pod api-7d9f -n prod | sed -n '/Events:/,$p'

Private registries

A pod can only use an imagePullSecret referenced by its spec or service account, in the same namespace. Verify the secret exists, contains the right registry host and credentials, and is attached to the service account used by the deployment. Rotate expired credentials and avoid copying secrets between namespaces.

Tags and architectures

A mutable tag can point to a different image than the one tested. Deploy by digest when reproducibility matters. On a mixed-architecture cluster, publish a multi-arch manifest; an amd64-only image will fail on arm64 nodes with a manifest error. Inspect the manifest rather than assuming the tag is portable.

Verify a clean pull

Delete the pod and let the controller recreate it, or run a temporary pod with the same image and secret. Confirm the image digest matches the expected build and the pod becomes Ready. A cached image on one node can hide a registry or credential problem on another.