highFoundationSymptom-first#pods#images#registry#imagepullbackoff

ImagePullBackOff / ErrImagePull — pod can't fetch its image

Pod stuck in ImagePullBackOff or ErrImagePull

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Pod stuck in ImagePullBackOff or ErrImagePull
  • Events show Failed to pull image
  • New deployments never start

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Image events

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

  • Resolved image reference

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

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Event: manifest for <image>:<tag> not found
  • Tag typo or a tag that was deleted after retagging

Confirm before fixing

docker manifest inspect <registry>/<image>:<tag>
READ

Check the tag exists remotely

Fix

kubectl set image deployment/<deploy> <container>=<registry>/<image>:<correct-tag>
CHANGE

Point at the correct tag

Expected: deployment.apps/<deploy> image updated

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

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

Read the exact pull error

2
docker manifest inspect <registry>/<image>:<tag>
READ

Prove the image exists before touching the cluster

3
kubectl get secret regcred -n <namespace>
READ

Confirm the pull secret is present and in the correct namespace

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

Create credentials if absent, then reference imagePullSecrets in the pod spec

Prevention

  • Use immutable tags (commit SHAs) and retag via pipeline, never overwrite mutable tags.
  • Store registry credentials as imagePullSecrets and attach at the ServiceAccount level.
  • Use IRSA on EKS / Workload Identity on GKE instead of static credentials.
  • Pre-pull images on node pools for cold-start prevention.

Related runbooks

Same stack, same failure family — worth a skim.

CrashLoopBackOff — container keeps crashing and restartingcritical

kubectl get pods shows CrashLoopBackOff status

KubernetesFoundation4 causes
Open runbook
Pods stuck in Pending state — unschedulablehigh

kubectl get pods shows Pending for minutes

KubernetesIntermediate3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.