◆Error Codes Wiki

Kubernetes ImagePullBackOff — Container Image Download and Registry Errors

Errordocker

Overview

Fix Kubernetes ImagePullBackOff when pods cannot pull container images from registries due to authentication, network, or image name errors.

Key Details

  • ImagePullBackOff occurs when Kubernetes cannot download the container image specified in the pod spec
  • ErrImagePull is the initial error; ImagePullBackOff is the state after multiple failed attempts
  • Private registries require imagePullSecrets configured in the pod spec or service account
  • Image tags like 'latest' may not exist or may have been overwritten
  • Network policies or firewall rules may block the node from reaching the container registry

Common Causes

  • Image name or tag does not exist in the registry (typo, deleted tag, wrong registry)
  • Private registry authentication credentials not configured or expired
  • Node network cannot reach the container registry (firewall, proxy, DNS)
  • Registry rate limits exceeded (Docker Hub limits pulls for free accounts)

Steps

  1. 1Check events: 'kubectl describe pod [name]' — the Events section shows the exact pull error message
  2. 2Verify image exists: 'docker pull [image:tag]' locally to confirm the image and tag are valid
  3. 3For private registries: create imagePullSecret — 'kubectl create secret docker-registry [name] --docker-server=[registry] --docker-username=[user] --docker-password=[pass]'
  4. 4Add imagePullSecrets to pod spec or patch the default service account
  5. 5For Docker Hub rate limits: authenticate pulls or use a mirror/cache registry

Tags

kubernetesimagepullbackoffcontainerregistryimage

Related Items

linux-kubernetes-pod-crashloopbackoff

More in Docker

linux-docker-common-errorsLinux Docker Common Errors — Container, Network & Volume Troubleshooting
Error
linux-docker-container-errors-detailedDocker Container Errors — Exit Codes, OOMKilled, and Networking Issues
Error
linux-container-permission-namespaceLinux Container Permission Errors — User Namespaces and Rootless Containers
Warning
linux-kubernetes-pod-crashloopbackoffKubernetes CrashLoopBackOff — Pod Restart Loop and Container Crash Debugging
Error
linux-docker-compose-network-errorDocker Compose Network Errors — Container Communication and DNS Resolution Failures
Warning

Frequently Asked Questions

Create a docker-registry secret with 'kubectl create secret docker-registry', then reference it in the pod spec under imagePullSecrets, or add it to the default service account for automatic use.