Troubleshoot Kubernetes ImagePullBackOff

Before you begin

A shell and access to the target environment; use authorized, non-production practice systems for changes.

Record the host, time, user impact, and recent changes. Begin with read-only checks so you have evidence before modifying a running system.

Inspect and understand

Events distinguish not found, denied, rate limited, and timeout. imagePullSecrets are namespaced; do not print their values.

kubectl describe pod POD -n NAMESPACE
kubectl get pod POD -n NAMESPACE -o jsonpath="{.spec.containers[*].image}"
kubectl get secret -n NAMESPACE

Read the command output in context. Confirm the exact host, process, resource, account, cluster, or workspace before taking action. Missing output can also reflect permissions or a different tool version.

Act on what you find

Change one identified cause at a time. Prefer the system’s service manager, deployment source, package manager, or configuration owner rather than editing a generated or ephemeral state directly.

For infrastructure, network, firewall, and service changes, follow the local approval and rollback procedure. Keep sensitive values out of shell history, logs, screenshots, and public tickets.

Verify and follow up

Correct image or approved identity, then confirm the new Pod pulls the intended content and reaches Ready.

Compare the result with the original symptom, check logs or health indicators, and note the change and any remaining uncertainty. A successful command exit does not always prove the service is healthy.