Fix ImagePullBackOff OpenShift¶
Introduction¶
ImagePullBackOff in OpenShift means the node cannot pull the image. Check the image name, registry access, pull secret, ImageStreamTag, and pod events.
Symptoms¶
Typical symptoms include failed pods, route errors, denied requests, unhealthy operators, or command errors that repeat after retries.
Common Causes¶
- Fixing the Deployment before reading the exact registry error.
- Creating a pull secret but not linking it to the service account.
- Using an image tag that does not exist.
Step 1: Check the Current Status¶
oc describe pod web-7c9d7f6f8b-jx4mk -n app
oc get secret pull-secret -n app
oc secrets link default pull-secret --for=pull -n app
oc rollout restart deployment/web -n app
Example output:
Warning Failed 38s kubelet Failed to pull image "quay.io/example/web:v2": unauthorized: access to the requested resource is not authorized
Step 2: Inspect Logs and Events¶
oc describe pod -l app=web -n app
oc get secret -n app
oc get istag -n app
Step 3: Verify Configuration¶
Compare the object selectors, service account, image reference, route target, or operator status with the failing symptom. In OpenShift, events often show the exact admission, scheduling, pull, SCC, or route reason.
Step 4: Apply the Fix¶
Apply the smallest targeted fix: correct the selector, update the route or service port, link the pull secret, grant the specific RBAC or SCC permission, or repair the unhealthy operator dependency.
Step 5: Confirm the Problem Is Resolved¶
Run the verification commands again and confirm the status, events, and user-facing test all agree.
Common Mistakes¶
- Fixing the Deployment before reading the exact registry error.
- Creating a pull secret but not linking it to the service account.
- Using an image tag that does not exist.
Quick Checklist¶
- Confirm the active project.
- Inspect the exact object named in the error.
- Read recent events.
- Apply one focused fix.
- Verify status after the change.
Related Guides¶
Summary¶
Fix ImagePullBackOff OpenShift requires matching the symptom to the OpenShift object that owns it. Use oc status commands, events, logs, and focused verification so the fix is tied to evidence.