Fixing AWS ECR Push Error: 'no basic auth credentials'

The ProblemYou run docker push and expect your image to head to the cloud. Instead, it fails instantly. You see a frustrating 'no basic auth credentials' error, even though everything worked perfectly yesterday. This usually happens because your local Docker environment has lost its connection to the AWS mothership.

$ docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
The push refers to repository [123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app]
Error response from daemon: no basic auth credentials

Why This HappensThe core issue is simple: your Docker client is no longer authenticated. Usually, it means your session token died.

AWS ECR authorization tokens are short-lived. By default, they expire every 12 hours. This is a security feature to ensure that compromised credentials don't grant indefinite access. Unlike Docker Hub, where a login might last for weeks, ECR requires you to refresh your 'password' at least twice a day if you're pushing frequently.

Step-by-Step Fix### 1. Check Your AWS IdentityFirst, verify who you are in the terminal. AWS might be trying to use a different set of credentials than you expect. Run this to see your current active profile:

aws sts get-caller-identity

If this returns an error, your AWS CLI isn't configured. Run aws configure to set your Access Key and Secret Key before proceeding.

2. Refresh the Token (AWS CLI v2)Most modern setups use AWS CLI version 2. Use the get-login-password command to fetch a fresh token and pipe it directly into Docker. It’s the cleanest way to log in.

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Quick checklist:

• Swap us-east-1 for your actual region (like eu-west-1).
• Replace 123456789012 with your 12-digit AWS Account ID.
• Keep the username as AWS. It is a static string, not your IAM name.

3. The Fix for AWS CLI v1 (Legacy)If you're maintaining an older build server with CLI v1, the command is slightly different. It generates a full command string that you must execute using a subshell:

$(aws ecr get-login --no-include-email --region us-east-1)

4. Managing Multiple ProfilesJuggling work and personal AWS accounts? You might be authenticated for the wrong one. Force the CLI to use a specific profile by adding the flag:

aws ecr get-login-password --region us-east-1 --profile work-profile | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Verifying the FixLook for the Login Succeeded message. Once you see it, retry your push. It should work immediately. If it still fails, peek into your ~/.docker/config.json file. Sometimes, external credential helpers (common on Docker Desktop for Mac or Windows) cache old data. Check the auths section to ensure the ECR registry URL matches your push destination exactly.

Pro Tips for Prevention### Automate with the ECR Credential HelperManual logins are a productivity killer. You can install the docker-credential-ecr-login helper. It handles the 12-hour refresh cycle automatically in the background. Once installed, you can run docker push any time without ever typing a login command again.

Verify IAM PermissionsYour IAM user needs the ecr:GetAuthorizationToken permission. Without it, the login command will fail with an "Access Denied" error before Docker even gets a chance to try. If you are using a CI/CD tool like GitHub Actions, ensure the runner's role has this permission attached.

Registry URL TyposOne missing character can break everything. The URL must follow: [account-id].dkr.ecr.[region].amazonaws.com. If you forget the dkr or ecr segments, Docker won't recognize the registry and will default back to that generic no basic auth error.

Keep Your Secrets SafeWhen creating IAM users for automated pushes, never reuse old passwords. I usually generate a 32-character random string for each new service. I've been using ToolCraft's Password Generator lately. It runs entirely in your browser, which is perfect for maintaining security standards without letting sensitive data touch someone else's server.