Kubernetes

●HIGH●Orchestration●BEGINNER

Kubernetes ImagePullBackOff Error

A pod is stuck in ImagePullBackOff and never reaches Running.

Est. Time

15 minutes

Version

v1.0.0

Updated

7/30/2026

Author

AutoDeploy Team

Setup Guide

Download guide

Kubernetes ImagePullBackOff Error

Problem

A pod is stuck in ImagePullBackOff or ErrImagePull and never reaches Running.

Symptoms

`kubectl get pods` shows ImagePullBackOff or ErrImagePull
`kubectl describe pod` events show 'Failed to pull image'

Root Cause

The kubelet can't pull the specified image — wrong image name/tag, a private registry with no imagePullSecret attached to the pod's service account, or the node has no network path to the registry.

Solution

1. Read the exact pull error from pod events

kubectl describe pod <pod-name> -n <namespace> | grep -A5 Events

2. Double-check the image reference in the manifest

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

3. Create an imagePullSecret for a private registry

kubectl create secret docker-registry regcred --docker-server=<registry> --docker-username=<user> --docker-password=<token> -n <namespace>

4. Attach it to the pod spec

spec:
  imagePullSecrets:
    - name: regcred

5. Or attach it to the whole service account so every pod in the namespace inherits it

kubectl patch serviceaccount default -n <namespace> -p '{"imagePullSecrets": [{"name": "regcred"}]}'

6. Test the pull manually from a node to rule out a network/firewall issue

docker pull <same-image-reference>

Prevention

Always attach imagePullSecrets when deploying to a namespace that uses private images
Use immutable, pinned tags rather than `latest` so a tag can't silently disappear
Add a CI check that verifies the image exists at the referenced tag before deploying

References

Pull an Image from a Private Registry

Last updated on 7/30/2026 · Part of the AutoDeploy DevOps Documentation library