docker: unauthorized: authentication required

You need to login to access this registry.

Frequently documented in developer and vendor support forums.

• Private repository
• Expired credentials
• Rate limit exceeded

1. Run docker login
2. Refresh access token
3. Wait for rate limit reset

Last reviewed: March 2026 How we review solutions

Docker returns "unauthorized: authentication required" when you attempt to pull or push an image to a registry that requires credentials, and your current Docker session does not have valid authentication for that registry. Docker Hub introduced rate limits and authentication requirements for pulls in November 2020, making this error far more common than before. Anonymous pulls from Docker Hub are limited to 100 pulls per 6 hours per IP address; authenticated free accounts get 200 pulls. Once the rate limit is hit, Docker Hub returns a 401 Unauthorized response even for public images. Private registries (AWS ECR, Google GCR, Azure ACR, GitHub Container Registry) always require authentication. Docker stores credentials in ~/.docker/config.json after a successful docker login, and these credentials can expire—AWS ECR tokens, for example, expire after 12 hours by default. CI/CD pipelines are particularly vulnerable because each pipeline run starts with a fresh environment and no cached credentials. The fix depends on which registry you are using: Docker Hub needs a simple docker login, while cloud registries have their own authentication helpers that generate short-lived tokens.

1. Run docker login to authenticate with the registry
2. Check if your credentials are expired: cat ~/.docker/config.json
3. For AWS ECR: run aws ecr get-login-password | docker login --username AWS --password-stdin
4. Verify the image name includes the correct registry prefix
5. Check Docker Hub rate limits: curl -s https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/alpine:pull | jq

Docker Hub rate limiting on shared CI IP

CI services share IP addresses across many customers. Even if your account has pulls remaining, the shared IP may have exceeded the anonymous limit. Always authenticate in CI pipelines to get per-account limits instead of per-IP limits.

Multi-stage build pulling from private registry

If your Dockerfile uses FROM private-registry.com/base:latest in a multi-stage build, Docker needs credentials for that registry even if the final image is pushed elsewhere. Use docker login for each registry referenced in the Dockerfile.

Credential helper misconfiguration

Docker can use platform-specific credential helpers (osxkeychain, wincred, pass). If the helper is configured but the credentials are not stored in it, docker pull fails silently. Check "credsStore" in ~/.docker/config.json.

How do I login?

Run docker login registry-url

Why rate limit?

Docker Hub limits pulls for anonymous users.

How long do Docker Hub credentials last?

Docker Hub access tokens do not expire by default, but personal access tokens can be set to expire. AWS ECR tokens expire after 12 hours. Always check the expiry policy for your specific registry.

Why does docker pull fail for a public image?

Docker Hub rate-limits anonymous pulls to 100 per 6 hours per IP. If you are behind a corporate network or shared CI, the IP may have exhausted its quota. Authenticate with docker login to get a higher per-account limit.

How do I authenticate Docker in a CI/CD pipeline?

Store registry credentials as CI secrets and run docker login in your pipeline script before any pull or push commands. For AWS ECR, use the aws-actions/amazon-ecr-login GitHub Action or equivalent for your CI platform.

• Docker CLI Reference – Official Docs
• Docker Daemon Configuration – Official Docs