Skip to content

ImagePullBackOff

Error message

                Failed to pull image: Back-off pulling image
              

Quick summary

The cluster cannot download the specified image from the registry, usually due to authentication, network, or image name issues.

Why this happens

  • The image does not exist in the specified registry

  • The registry requires authentication but no imagePullSecret is configured

  • The registry is unreachable due to network issues or firewall rules

  • The image name or tag is misspelled

Minimal example

✗ Broken code
# No imagePullSecret configured for private registry
image: registry.example.com/myapp:v1
✓ Fixed code
# Create and reference imagePullSecret
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass

# In Pod spec:
imagePullSecrets:
  - name: regcred

The private registry requires authentication. The fix creates a secret with credentials and references it in the Pod spec.

How to diagnose

  • Check Pod status: kubectl get pods — look for ImagePullBackOff

  • Describe the Pod for detailed error: kubectl describe pod <pod>

  • Try pulling the image manually: docker pull <image>

  • Verify imagePullSecrets are configured: kubectl get secrets

How to fix

  • Correct the image name and tag in the deployment manifest

  • Create an imagePullSecret and add it to the Pod spec

  • Fix network connectivity to the registry (check DNS, firewall, proxy)

  • Ensure the image has been built and pushed to the registry

How to prevent

  • Use CI/CD to automatically build and push images

  • Configure imagePullSecrets for private registries in each namespace

  • Use explicit image tags instead of latest

Related Resources

Related Glossary

← Back to language