How to Fix AWS EKS ImagePullBackOff Error in Kubernetes 1.30+
Quick Fix Summary
TL;DRCheck pod events for auth errors, verify ECR repository exists, and ensure IAM permissions are correctly configured for the service account.
ImagePullBackOff occurs when a Kubernetes pod cannot pull its container image from a registry. In AWS EKS, this is most commonly due to authentication failures with Amazon ECR or misconfigured IAM roles for service accounts.
Diagnosis & Causes
Recovery Steps
Step 1: Diagnose the Pod and Check Events
First, get the exact error message from the failing pod's events. This will point you to the specific cause (auth, network, missing image).
kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by='.lastTimestamp'Step 2: Verify ECR Authentication & IAM Permissions
Ensure the node or pod service account has the `ecr:GetAuthorizationToken` and `ecr:BatchGetImage` permissions. For IRSA, verify the trust relationship.
# Check IAM policy attached to node role or service account role.
aws iam list-attached-role-policies --role-name <EKS-Node-Role-Name>
# For IRSA, annotate your service account (if not using 1.30 OIDC auto-discovery)
kubectl annotate serviceaccount -n <namespace> <service-account-name> eks.amazonaws.com/role-arn=<IAM-ROLE-ARN>Step 3: Manually Authenticate and Test Image Pull
Authenticate Docker/containerd to ECR from a node shell to rule out broader auth issues. This tests the node's base permissions.
# Get ECR login command for your region
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com
# Attempt to pull the image directly
docker pull <account-id>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>Step 4: Validate Image Reference and Existence
Confirm the image repository and tag specified in your deployment manifest actually exist in ECR.
aws ecr describe-images --repository-name <repo-name> --image-ids imageTag=<tag> --region <region>
# Check deployment manifest
kubectl get deployment <deployment-name> -n <namespace> -o yaml | grep image:Step 5: Check Network Connectivity to ECR
If using private ECR or VPC endpoints, ensure network policies and security groups allow traffic to ECR endpoints (port 443).
# From a pod or node, test connectivity to ECR API and DKR endpoints.
curl -v https://api.ecr.<region>.amazonaws.com
nc -zv <account-id>.dkr.ecr.<region>.amazonaws.com 443Step 6: Restart the Pod with Updated Configuration
After fixing the root cause (IAM, auth, image), restart the deployment to force a new pod creation with correct configuration.
kubectl rollout restart deployment/<deployment-name> -n <namespace>
# Monitor new pod status
kubectl get pods -n <namespace> -wArchitect's Pro Tip
"For Kubernetes 1.30+ on EKS, leverage OIDC discovery for IRSA—it automates service account trust. Also, use ECR PrivateLink to avoid public internet routing and simplify network policies."
Frequently Asked Questions
My pod uses IAM Roles for Service Accounts (IRSA) but still gets ImagePullBackOff. What's wrong?
Verify the OIDC provider URL in your IAM role's trust policy matches your EKS cluster's. In 1.30+, ensure the `serviceAccountTokenVolumeProjection` feature is active. Check for typos in the service account annotation `eks.amazonaws.com/role-arn`.
The error is 'NotAuthorized: Not Authorized'. What does this mean?
This is a definitive ECR permissions error. The IAM entity (node role or pod service account role) lacks the `ecr:GetDownloadUrlForLayer` or `ecr:BatchGetImage` action permissions for the specific ECR repository ARN.
Can VPC endpoint policies cause ImagePullBackOff?
Yes. If your EKS nodes use a VPC endpoint for ECR (com.amazonaws.<region>.ecr.dkr), the endpoint policy must allow the `ecr:BatchGetImage` and `ecr:GetDownloadUrlForLayer` actions for the principal (e.g., the node IAM role).