ImagePullBackOff ☸️ Kubernetes

Kubernetes: ImagePullBackOff / ErrImagePull

The node can’t pull the container image — wrong name/tag, missing registry credentials, or registry unreachable.

Seen on: Kubernetes Docker

Meaning

kubectl describe pod shows the exact pull error: “not found”, “unauthorized”, “manifest unknown”, or a network timeout.

Common causes

  • Typo in image name or tag
  • Tag doesn’t exist (pushed under a different tag)
  • Private registry without imagePullSecrets
  • Expired registry credentials (ECR tokens last 12h)
  • Image built for a different CPU architecture
  • Registry rate limits (Docker Hub)

⚡ Quick fix

  1. kubectl describe pod → Events for the precise error
  2. Verify the image exists: docker pull <image>
  3. Create and reference an imagePullSecret
  4. Build multi-arch images (amd64/arm64)

Detailed fix by platform

Kubernetes

  1. Registry secret:
    bash
    kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io --docker-username=USER --docker-password=TOKEN
# then in the pod spec: imagePullSecrets: [{ name: regcred }]

How to diagnose

  1. Events — Exact pull error?
  2. Image — Name/tag exist?
  3. Auth — Pull secret configured?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.