EC
Init:ImagePullBackOff
KubernetesERRORNotablePod StateHIGH confidence

Init container image cannot be pulled

Production Risk

Application container blocked; deploy is stuck until image issue is resolved.

What this means

Init:ImagePullBackOff means Kubernetes is unable to pull the container image for an init container. The node attempted to pull the image, failed, and is now backing off with exponential delay before retrying. The application container never starts. This is the init-container variant of ImagePullBackOff.

Why it happens
  1. 1Init container image tag does not exist in the registry
  2. 2Registry credentials (imagePullSecrets) are missing or incorrect for the init container image
  3. 3Registry is unreachable from the node network
  4. 4Typo in the image name or tag
How to reproduce

Pod shows Init:ImagePullBackOff; init container image pull is failing.

trigger — this will error
trigger — this will error
kubectl describe pod mypod | grep -A 10 "Init Containers:"
# State: Waiting  Reason: ImagePullBackOff

kubectl get events --field-selector involvedObject.name=mypod | grep -i pull

expected output

State:          Waiting
  Reason:       ImagePullBackOff

Fix 1

Verify init container image name and tag

WHEN Image may not exist in the registry

Verify init container image name and tag
# Check the init container image reference
kubectl get pod mypod -o jsonpath='{.spec.initContainers[*].image}'

# Verify tag exists in registry
docker manifest inspect myregistry.io/myinitimage:tag

Why this works

Confirms the image reference is correct before investigating credentials.

Fix 2

Add imagePullSecrets for private registry

WHEN Init container image is in a private registry

Add imagePullSecrets for private registry
# Create secret
kubectl create secret docker-registry regcred   --docker-server=myregistry.io   --docker-username=myuser   --docker-password=mypassword

# Reference in pod spec
spec:
  imagePullSecrets:
  - name: regcred
  initContainers:
  - name: my-init
    image: myregistry.io/myinitimage:tag

Why this works

imagePullSecrets provides the credentials kubelet needs to authenticate with the registry.

Sources
Official documentation ↗

Kubernetes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Kubernetes errors