Container image pull failure

What this failure means

The deployment failed because the runtime could not pull the requested container image from the registry.

Symptoms

Faultline looks for one or more of these log fragments:

imagepullbackoff
errimagepull
failed to pull image
pull access denied for
back-off pulling image
rpc error: code = unknown desc = error response from daemon

Diagnosis

The deployment failed because the runtime could not pull the requested container image from the registry.

Fix steps

1. Verify the image name and tag in the deployment manifest exactly match a published image.
2. Confirm the cluster or runner has registry credentials for the target repository.
3. Inspect the imagePullSecrets or runtime credential configuration used by the deployment.
4. Check the latest successful build or release job to confirm the image was pushed before deploy started.
5. Inspect the pod events and confirm the failure is an image reference or credential issue rather than a broader scheduling problem.

Validation

• kubectl describe pod
• kubectl get events —sort-by=.lastTimestamp

Why it matters

The tag may not exist, the registry may require authentication, or the image reference in the deployment spec may point at the wrong repository.

Prevention

• Promote immutable image digests rather than mutable tags between build and deploy stages.
• Add a release gate that verifies the target image exists before rollout.
• Keep registry authentication and image naming conventions standardized across environments.
• Publish the image before creating or approving the deploy job so rollout never races the registry push.

Try it locally

docker pull <image>:<tag>
kubectl describe pod <pod>
kubectl get events --sort-by=.lastTimestamp

How Faultline detects it

Use faultline explain image-pull-backoff to see the full playbook.

faultline analyze build.log
faultline explain image-pull-backoff

Generated from playbooks/bundled/log/deploy/image-pull-backoff.yaml. Do not edit directly.