Q: Your Docker push to ECR fails in CI: `no basic auth credentials`.
When a Docker push to ECR fails with no basic auth credentials, the Docker client has no valid credential stored for that exact registry hostname.
Want to master this scenario in a live sandbox? KodeKloud's Enterprise GitOps with ArgoCD & Kubernetes Rollouts covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: When a <strong>Docker push to ECR fails with <code>no basic auth credentials</code></strong>, the Docker client has no valid credential stored for that exact registry hostname. Nearly always the fix is to run <code>aws ecr get-login-password</code> piped into <code>docker login</code> for the right account and region in the same job and user context that runs the push. Interviewers use this scenario to test whether you debug methodically: identity, region, credential store, token lifetime and IAM permissions, instead of retrying the pipeline and hoping.
Symptom and mental model
The error comes from the Docker client before AWS permission checks, so it is about credentials being absent, not about IAM denial.
- Typical output:
no basic auth credentialsondocker push, often right after the build succeeded. A permissions problem usually showsdeniedornot authorizedinstead. - How ECR auth works: ECR does not use your AWS keys directly.
ecr get-login-passwordreturns a temporary token (valid for 12 hours) that you give to Docker as the password for userAWS. - Registry host is the key: Credentials are stored per hostname such as
123456789012.dkr.ecr.us-east-1.amazonaws.com. A login for another account or region does not apply. - Order of checks: Who am I, which registry, did I log in, where were credentials stored, does the role have push rights, does the repository exist.
- Quick triage question: Did this ever work on this runner? If yes, suspect token expiry or a changed environment; if never, suspect a missing login step.
Hands-on: fix the Docker push to ECR login
Verify identity first, then log in explicitly with AWS CLI v2.
aws sts get-caller-identity
REGION=us-east-1
ACCOUNT=123456789012
REGISTRY=${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com
aws ecr get-login-password --region $REGION \
| docker login --username AWS --password-stdin $REGISTRY
# Login Succeeded
docker tag my-app:1.4.2 $REGISTRY/my-app:1.4.2
docker push $REGISTRY/my-app:1.4.2
- Confirm identity:
aws sts get-caller-identityshows the account and role the job is using; the account must match the registry hostname. - Log in: Pipe the password to
docker login --password-stdinso it never appears in process lists. - Match region: Use the region of the repository in both
--regionand the registry host. - Retry the push: Tag with the full registry path and push.
- Windows and Mac helpers: Desktop installs may use credential helpers such as
osxkeychainorwincred, which behave differently from the plainauthsfile on Linux runners.
Ordered diagnostic checks when login looks correct but push still fails
Walk the list from the most common cause to the least.
cat ~/.docker/config.json | jq '.auths | keys, .credsStore, .credHelpers'
echo "$DOCKER_CONFIG"
docker info | grep -i -A2 registry
docker buildx ls
- Login in a different context: The credential file belongs to a user. A login as one user and a push through
sudo docker, a different Jenkins agent or another container will not share credentials. Check~/.docker/config.jsonfor the registry underauthsor acredsStoreorcredHelpersentry. - Custom DOCKER_CONFIG: If the pipeline sets
DOCKER_CONFIGto a temp directory, login and push must use the same one. - Wrong registry string: The image tag must start with the exact host used in login. A typo, a different region or a different account gives this same error.
- Token expired: A cached login from a long-lived runner is older than 12 hours. Always log in at the start of the job.
- Buildx or docker-in-docker: A build that pushes from a separate builder container needs credentials available to that builder, and a DinD service has its own empty config.
Permissions, repository and public ECR edge cases
After authentication works, the next layer is IAM and repository settings.
- Required IAM actions:
ecr:GetAuthorizationToken(resource*) plus push actions on the repository:BatchCheckLayerAvailability,InitiateLayerUpload,UploadLayerPart,CompleteLayerUploadandPutImage. - Repository must exist: ECR does not create repositories on push; you will see a repository-does-not-exist error. Create it with
aws ecr create-repository. - Immutable tags: Pushing an existing tag to an immutable repository fails with a tag-invalid error, which is different from the auth failure.
- ECR Public: It uses
aws ecr-public get-login-password --region us-east-1and the hostpublic.ecr.aws, and the API is only in us-east-1. - Cross-account pushes: Pushing to another account's repository needs a repository policy there allowing your principal, in addition to your own IAM policy.
Prevention: keyless, repeatable login in CI
Make the login a standard first step with short-lived credentials.
- GitHub Actions OIDC: Use
aws-actions/configure-aws-credentials@v4withrole-to-assume, thenaws-actions/amazon-ecr-login@v2, instead of storing access keys. - Least privilege role: Scope push permissions to specific repository ARNs, and give deploy clusters pull-only roles.
- Fail fast: Add
aws sts get-caller-identityand a login step before the build so credential problems fail in seconds, not after a 10-minute build. - Mask and avoid logging: Never echo the password; use
--password-stdinand keep debug output free of tokens. - Observability: Check CloudTrail for
GetAuthorizationTokenevents to confirm the job actually requested a token and which role made the call.
- no basic auth credentials means Docker has no stored login for that registry host; the fix is aws ecr get-login-password piped into docker login for the right account and region.
- I verify with sts get-caller-identity, the auths section of the docker config, and a test push of a small tag.
- I automate with OIDC role assumption, the amazon-ecr-login action and a fail-fast login step at the start of each job.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Logging in once on a long-lived runner The ECR token expires after about 12 hours, so later jobs fail with the same error.
- Logging in as one user and pushing as another Docker stores credentials per user config, so sudo or a different agent user has none.
- Logging in to the wrong region or account host Credentials apply only to the exact registry hostname, so the push still lacks auth.
- Adding broad ecr:* permissions to fix it The error is about missing credentials, so wider IAM does not help and weakens security.