toomanyrequests: You have reached your pull rate limit

TL;DR: Authenticate to raise the limit: docker login with a free Docker Hub account raises you from the anonymous quota (100 pulls per 6h per IP) to 200 pulls per 6h per account, and paid tiers go higher. For CI, authenticate every pull and cache base images locally so one pull serves many jobs.

The error

toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

Fix it

1. Check current limit headers. First fetch a token -

curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token then call the endpoint with it as the bearer token - curl -sI -H "your auth header https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest Expected: RateLimit-Limit and RateLimit-Remaining headers show your quota.

1. Log in to get the authenticated quota:

docker login Expected: Login Succeeded.

1. Reduce pull consumption: pin base images, use docker pull once and share the daemon across CI jobs, or mirror to your own registry.

When this applies

• CI/NAT environments where many hosts share one outbound IP (the limit is per IP for anonymous pulls)
• Frequent rebuilds pulling the same base images

When this does NOT apply

• "unauthorized" (credential problem)
• Private registries (no Hub rate limit)

Versions

All Docker versions; Hub policy since late 2020.

Why it happens

Docker Hub throttles pulls per IP (anonymous) or per account (authenticated) to control bandwidth costs. NAT and shared CI runners burn through the anonymous quota fast.

Edge cases

• The limit counts manifest fetches; multi-arch pulls and buildx bake can consume several per image.
• Paid Hub plans (Pro/Team/Business) raise limits substantially; for heavy CI it is usually cheaper than engineering around it.
• Some base images are mirrored on GHCR/ECR Public with no such limit; switching the FROM can dodge the problem entirely.