Docker login fails with 'unauthorized: authentication required'

You type docker login myregistry.azurecr.io and boom—unauthorized: authentication required. Maybe you used the right username and password. Maybe you even copy-pasted it from a password manager. Still fails. I've seen this exact error pop up more times than I can count, especially after a password rotation or when someone changes their Azure AD credentials.

What's actually going on?

Docker stores your login info in a file called ~/.docker/config.json. That file saves the credentials in base64 (not encrypted—just encoded). When the registry rejects you, it's because:

1. The stored credentials are old or wrong.
2. You typed the username or password wrong.
3. The registry requires a token (like an access key) instead of a password.
4. Your Docker client version is too old (rare but happens on CentOS 7 with Docker 1.13).

Most of the time, it's reason #1. Especially with Azure Container Registry—if you use AD tokens, they expire after 1 hour by default. Same with AWS ECR tokens—they expire after 12 hours. Use the wrong one and you get this error.

The fix

Skip the rabbit hole of checking firewall rules and network policies. Do this first:

Step 1: Log out completely

docker logout myregistry.azurecr.io

This clears the stored creds. If you don't specify the registry server, it logs out of Docker Hub. Be specific.

Step 2: Log back in with the right credentials

For Azure Container Registry:

az acr login --name myregistry

This uses your Azure CLI token. Works 99% of the time. If you don't have the Azure CLI, use admin credentials:

docker login myregistry.azurecr.io --username myregistry --password <admin-password>

For AWS ECR:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com

For Google Container Registry:

gcloud auth configure-docker

For Docker Hub: just run docker login and enter your username and password. If you have 2FA enabled, use an access token (not your password).

Step 3: Verify it worked

docker pull myregistry.azurecr.io/hello-world:latest

If that pulls, you're good. If not, go to step 4.

Still failing? Check these

• Registry URL typo—I had a client who typed azurecr.io as azurerc.io. Took 20 minutes to spot.
• Admin account disabled—on Azure Container Registry, go to Settings > Access keys and make sure Admin user is Enabled. If it's Off, you can't use username/password login.
• Token expiration—AWS ECR tokens expire after 12 hours. If you generated it yesterday, it's dead. Run the command again.
• Docker version—check with docker --version. If you're on anything before 18.09, upgrade. Old versions don't support credential helpers.
• Corporate proxy—if you're behind a proxy, Docker needs HTTP_PROXY and HTTPS_PROXY set. Add them in /etc/systemd/system/docker.service.d/proxy.conf and restart Docker.

Had a client last month whose entire CI pipeline broke because someone changed the GitLab personal access token. The fix was just updating the token in the Docker config file. Took 2 minutes.

One more thing—if you're using a private registry with self-signed certs, add the cert to Docker's trust store. Otherwise Docker will refuse to connect and give you a different error (usually certificate-related). But that's a story for another article.