Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Docker toomanyrequests: You have reached your pull rate limit

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

A docker pull or a deployment fails with toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits. Docker Hub is refusing further image pulls from your account, or from your public IP address if you are not signed in, until the current 6-hour window allows more. The quick fix is to sign in with docker login. The lasting fix is to pull less often, or to pull through a cache you control (Docker's mirror page does not say how cache hits are counted). Figures on this topic change, so check the current Docker page.

What the error means

Docker's pull usage page says unauthenticated and Docker Personal users are subject to a pull rate limit on Docker Hub per 6 hours, and Docker Pro, Team and Business users have an unlimited pull rate, subject to fair use. On 20 November 2026 it listed:

User type Pull rate limit per 6 hours
Business, Team, Pro (authenticated) Unlimited
Personal (authenticated) 200
Unauthenticated users 100 per IPv4 address or IPv6 /64 subnet

These figures can change. Check the current page, Docker Hub pull usage and limits, before you plan around them.

When you are over the limit, the page says Docker Hub returns a 429 response code with the body You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits when the manifest is requested, and that the message appears in the Docker CLI or in the Docker Engine logs.

The toomanyrequests: prefix comes from the registry error code. The OCI Distribution Specification (main branch) lists an error code TOOMANYREQUESTS with the description "too many requests". The Distribution project's Go error package formats an error as the lower-case code followed by a colon and the message, which matches the toomanyrequests: prefix in front of the Docker Hub text.

How pulls are counted, from the page: a pull includes both a version check and any download that results; version checks do not count towards the limit. A pull of a normal image is one pull for a single manifest, and a pull of a multi-architecture image counts as one pull for each different architecture. For unauthenticated users the limit is per IPv4 address or IPv6 /64 subnet, so many servers behind one public address share one allowance.

The Docker Hub usage and limits page separates this from a different limit: an abuse rate limit that applies to all requests to Docker Hub properties, per IPv4 address or IPv6 /64 subnet, which returns a simple 429 Too Many Requests response. The pull limit returns the longer message with a link to documentation.

Likely causes

Cause What you see How to confirm
Unauthenticated pulls from a shared public IP Failures across several servers at once, each pulling fine earlier The rate limit header shows a limit of 100 for the window and the source IP matches your NAT address
Authenticated Personal account at its limit Failures after signing in The header shows a limit of 200 and the remaining count is 0
A CI or deploy loop pulling the same images repeatedly Pull count climbs with every build Pull history in your logs, or the monthly usage report in Docker Hub
Many architectures pulled for one image Multi-platform builds use more than expected The page says each architecture counts as one pull
A third-party platform shares one address Failures even when signed in The page says platforms may use the same address for many users, which can trigger abuse limiting
The simple 429 abuse limit No long message, only 429 Too Many Requests The error body lacks the pull-limit text

Prove the cause before changing anything

All of these are read-only on your servers. They contact Docker Hub's token and registry endpoints.

1. Read your own limit and remaining count. The Docker page gives these steps. You need curl and jq. Get an anonymous token for the page's test repository:

TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)

Then request the headers only:

curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest

The page says to examine the headers ratelimit-limit, ratelimit-remaining and docker-ratelimit-source, and shows the values 100;w=21600, 20;w=21600 and an address. It explains that 100;w=21600 means 100 pulls per 21,600 seconds, which is 6 hours (21,600 ÷ 3,600 = 6), with 20 remaining. The page says a HEAD request does not count towards the limit but a GET does, so use --head as shown.

2. Check which address Docker sees. The docker-ratelimit-source header shows the source address. On servers behind NAT this is the shared public address, not the server's own.

3. If no limit headers appear, the page says it can be because the image or your address is unlimited through a partnership, or because the account you pull as has a paid subscription. In that case the error you saw may be the other 429 limit.

4. Check whether you are signed in. The page says authentication is needed for correct attribution of pulls. On a server, check how your deploy or CI process logs in, rather than assuming your own session applies.

Fix

1. Sign in. The Docker page says to run docker login on a standalone Engine to authenticate with Docker Hub. By default docker login uses a web-based device flow, where you enter a code in a browser. For a server or pipeline, the docker login reference shows reading the secret from standard input so it stays out of shell history: cat ~/my_password.txt | docker login --username foo --password-stdin, and it accepts a Personal Access Token in place of a password. Prefer a token created for that one purpose.

Save the current Docker client configuration first. The docker login reference gives its location as $HOME/.docker/config.json on Linux, and says that without a configured credential store the credentials are kept in that file. If the file does not exist, there is nothing to save:

cp -p $HOME/.docker/config.json $HOME/.docker/config.json.2026-11-20.bak

Risk: the credentials are saved in the configured credential store on that host, or in config.json if none is configured, so anyone who can read that store can pull as that account, and pulls count against that account's allowance. A host already signed in as another account may lose that stored sign-in. Back-out: if the host held no credentials before, docker logout, which logs out from the registry (the default is defined by the daemon). If it held credentials in config.json, docker logout removes the login but does not bring the earlier one back; copy $HOME/.docker/config.json.2026-11-20.bak back over $HOME/.docker/config.json. If you use an external credential store, the saved file does not hold the stored secrets, so sign in again with the earlier account.

docker login

Other platforms need their own setting, as the page lists: Docker Swarm needs the --with-registry-auth flag, GitHub Actions uses a login action, and for Kubernetes the page links its guide "Pull an Image from a Private Registry".

2. Pull less. Do not pull the same image on every build or restart. As general advice, keep images in a local registry or cache between runs, pin the tag you deploy, and remove loops that pull repeatedly. Counting arithmetic: a pipeline that pulls 4 images per run reaches 100 pulls after 100 ÷ 4 = 25 runs.

3. Pull through a cache. The Docker registry mirror page describes running a registry as a pull-through cache, and shows configuring the Docker daemon with a registry-mirrors key in /etc/docker/daemon.json (or the --registry-mirror option for dockerd). Save the current file first:

cp -p /etc/docker/daemon.json /etc/docker/daemon.json.2026-11-20.bak

Then add the registry-mirrors key from the mirror page to /etc/docker/daemon.json, merging it with any keys already there, and check the result (the dockerd reference describes --validate as checking a configuration file without starting the daemon):

dockerd --validate --config-file /etc/docker/daemon.json

Risk: the mirror page says to "reload Docker for the change to take effect". The dockerd reference lists registry-mirrors among the options that can be reconfigured while the daemon runs, using the SIGHUP signal on Linux, without restarting the process; a full restart is not needed for this key. If the daemon finds a conflict with its command-line flags, it "fails to reconfigure itself" but keeps running. Back-out: copy /etc/docker/daemon.json.2026-11-20.bak back over /etc/docker/daemon.json, run the validate command again, then reload the daemon again. If the mirror needs credentials for private images, the mirror page warns that private resources visible to that user are made available on the mirror, so secure it. The mirror page also says mirrors of Docker Hub are still subject to Docker's fair use policy, and it does not state how requests served from a cache are counted against the pull limit.

4. Change plan. The page lists unlimited pulls for paid plans, subject to fair use. Check the current page and Docker's pricing for terms; they change.

5. Wait. The limit is calculated on a 6-hour basis. Waiting is the only fix if you cannot sign in and need no more pulls in the meantime.

Example (illustrative): two CI runners, ci01 and ci02, build from the same office network, whose public address is 203.0.113.9. Builds start failing with toomanyrequests: You have reached your pull rate limit. The curl --head check from ci01 shows ratelimit-limit: 100;w=21600, ratelimit-remaining: 0;w=21600 and docker-ratelimit-source: 203.0.113.9, so the two runners and everything else on the office address share one unauthenticated allowance. Each build pulls 4 images, and 100 ÷ 4 = 25 builds exhaust it. The team signs both runners in with a token created for CI, reduces pulls with a local cache, and keeps an eye on the headers.

Confirm the fix

Repeat the header check using an authenticated token as the page describes (it uses curl --user with credentials; the docker login reference says that passing the password on standard input keeps it out of shell history and log files, so be careful where you type a secret). The ratelimit-limit value should now show your account's limit; on an unlimited paid plan the headers may not appear at all (see "If no limit headers appear" under "Prove the cause before changing anything"), so a successful pull is then the check. Then run the pull that failed. In CI, check that the log shows a successful pull and that the remaining count stays comfortably above zero.

What to watch afterwards

  • The remaining count from the ratelimit-remaining header, or the monthly usage report in Docker Hub that the page describes.
  • Jobs that pull on every run, and images pulled for several architectures.
  • Docker's own page for changes to the numbers.
  • Any other service behind the same public address; they share an unauthenticated allowance.

Risks and limits

The figures here describe Docker Hub's documented behaviour at the date accessed. Plans, limits and terms change, so read Docker's current page and pricing. Signing in uses an account credential, which must be protected. A registry mirror or cache is infrastructure you operate, with its own storage and security. These commands have not been run or lab-tested.

Sources