Private ECR registries do not use long-lived Docker passwords. Instead, you obtain a temporary authorization token from AWS and pipe it into docker login.
aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` After that, a pull works normally: ```bash docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest ``` If the login step is skipped, expired, or targets the wrong registry, Docker reports `no basic auth credentials`. ## Check Region and Registry Carefully ECR authentication is registry-specific and region-specific. A successful login to one registry does not automatically authorize a pull from another registry in another region. So verify these three values match the image you are pulling: - AWS account ID - region - registry hostname For example, if the image lives in `us-west-2`, logging in to `us-east-1` will not help. ## Verify AWS Identity Before Debugging Docker Before changing Docker config, confirm that the AWS CLI itself can authenticate and that the caller has permission to access ECR. ```bash aws sts get-caller-identity aws ecr describe-repositories --region us-east-1 ``` If these commands fail, Docker is not the first problem. Fix the AWS credentials or IAM permissions first. The minimum useful ECR permissions for pulls usually include access to authorization tokens plus repository read actions such as image lookup and layer download. ## Common CI and Kubernetes Failure Mode This error appears frequently in CI pipelines and containerized environments because the login step is missing from the runtime environment, even though it worked on a developer laptop. A safe CI pattern looks like this: ```bash aws ecr get-login-password --region "$AWS_REGION" \ | docker login --username AWS --password-stdin "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com" docker pull "$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/my-app:$IMAGE_TAG" ``` Make sure the job actually has AWS credentials at runtime and that they are not expired or incomplete. ## Docker Credential State Can Also Be Stale Sometimes the system does have Docker auth state, but it is stale or points to the wrong registry. Useful checks: ```bash cat ~/.docker/config.json ``` And if needed, clear the old state and log in again: ```bash docker logout 123456789012.dkr.ecr.us-east-1.amazonaws.com aws ecr get-login-password --region us-east-1 \ | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` This is especially helpful after switching accounts or roles. ## Cross-Account and Role Assumption Cases If the repository lives in a different AWS account, the pulling identity needs both: - valid AWS credentials for the caller - repository access granted by IAM and repository policy In those setups, the login command may succeed because the caller can get an authorization token, but the pull can still fail later if the repository policy does not allow image access. So if the auth error changes into an access-denied error after re-login, that is progress. It means Docker auth is now working and the remaining issue is authorization policy. ## EKS, ECS, and Node-Level Pulls When containers are pulled by orchestrators, the relevant identity may be the node role, task role, or kubelet integration rather than your shell user. That means debugging with a local `docker login` on your workstation can be misleading. In cluster environments, verify which machine or runtime is performing the pull and whether that execution identity has ECR access. This is a very common source of confusion in EKS and ECS troubleshooting. ## Common Pitfalls The biggest mistake is running `docker pull` before logging in to the exact ECR registry hostname. Another mistake is using the wrong region in `aws ecr get-login-password`. The token is tied to the registry region. Teams also often assume a successful AWS CLI login automatically means Docker is logged in to ECR. It does not. The Docker registry login is a separate step. Finally, do not debug local shell behavior when the failing pull is actually being performed by CI, ECS, Kubernetes, or another remote runtime. ## Summary - '`no basic auth credentials` usually means Docker is not currently logged in to the target private ECR registry.' - Use `aws ecr get-login-password | docker login ...` for the exact account and region. - Verify AWS identity and ECR permissions before blaming Docker. - Refresh stale Docker registry auth if account or role context changed. - In orchestrated environments, debug the identity that performs the pull, not just your local shell.
