Kubernetes ECR Pull "no basic auth credentials" - Fix in CI

By Kaveh Alemi·Latchkey

A pull from Amazon ECR failed with no basic auth credentials. ECR requires a short-lived auth token; either the node’s IAM role lacks ECR read permission, or no valid credential was supplied for the pull.

What this error means

Pods pulling an ECR image (<acct>.dkr.ecr.<region>.amazonaws.com/...) fail with ErrImagePull and pull access denied ... no basic auth credentials, while non-ECR images pull fine.

kubectl describe pod

Failed to pull image "123456789012.dkr.ecr.us-east-1.amazonaws.com/api:1.0":
pull access denied ... no basic auth credentials

Common causes

Node IAM role lacks ECR permission

On EKS, the kubelet uses the node’s instance role to fetch ECR credentials. Without ecr:GetAuthorizationToken and ecr:BatchGetImage/GetDownloadUrlForLayer, the pull is unauthorized.

Expired or missing ECR token (off-cluster nodes)

For non-EKS nodes or external runners, the 12-hour ECR auth token expired or was never created, so there are no basic auth credentials to present.

How to fix it

Grant the node role ECR read permissions

Attach an ECR read policy to the node/instance role so the kubelet credential provider can fetch tokens.

Terminal

# the node role needs at least:
# ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability,
# ecr:GetDownloadUrlForLayer, ecr:BatchGetImage
aws iam attach-role-policy --role-name <eks-node-role> \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

Refresh the ECR pull secret on non-EKS clusters

Where the kubelet cannot fetch tokens itself, create/refresh a docker-registry secret from a fresh ECR login (tokens last ~12h).

Terminal

TOKEN=$(aws ecr get-login-password --region us-east-1)
kubectl create secret docker-registry ecr-creds \
  --docker-server=123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --docker-username=AWS --docker-password="$TOKEN" --dry-run=client -o yaml \
  | kubectl apply -f -

How to prevent it

On EKS, attach AmazonEC2ContainerRegistryReadOnly (or scoped equivalent) to the node role.
Avoid static ECR secrets - they expire in ~12 hours; automate refresh if you must use them.
Confirm the ECR repo policy allows the pulling principal.

Frequently asked questions

What causes ""no basic auth credentials" (ECR)"?

On EKS, the kubelet uses the node’s instance role to fetch ECR credentials. Without ecr:GetAuthorizationToken and ecr:BatchGetImage/GetDownloadUrlForLayer, the pull is unauthorized.

How do I fix "no basic auth credentials" (ECR)?