Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker Hub: toomanyrequests and the pull rate limit behind it

Shared CI addresses drain the anonymous quota. Log in, cache the bytes once, and stop pulling production images from Docker Hub.

~6 min readDocker
#Docker#Docker Hub#CI#Registries
A registry tower with a layer stack and a cyan token key beside an amber quota meter filled to the top

Introduction & Quick Summary

A build or a docker pull stops 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. The image exists, the tag is correct, and the same command worked an hour ago. What ran out is not disk, credentials or network - it is the anonymous pull quota attached to the public IP your CI runner shares with everyone else on that cloud provider.

Docker Hub counts manifest and layer pulls per six-hour window, per account when authenticated and per IP when not. Shared CI egress ranges are the worst case: dozens of unrelated jobs pull node:22, postgres:17 or ubuntu:24.04 from the same address and drain the anonymous bucket for everybody.

The fixes, in the order that actually holds up under CI load:

  1. Authenticate every pull. A free Docker Hub account raises the limit and moves the counter from a shared IP to your account; a CI secret with docker login --password-stdin is a two-line change.
  2. Stop pulling the same base image on every job. A pull-through cache or a registry mirror inside your network serves the bytes once and reuses them.
  3. Do not depend on Docker Hub for production images. Copy what you need into a registry you control (GHCR, ECR, Artifact Registry), pin by digest, and pull from there.

What does not fix it: retrying in a loop, which spends the remaining budget faster, and switching to an unofficial mirror you do not control.

Core Mechanics, Signatures & Reproducible Setup

Every pull is two requests: a manifest fetch and one per missing layer. Docker Hub applies the limit at the manifest level, so a cached layer does not reduce the count when the manifest is refetched. Anonymous pulls are counted per public IP; authenticated pulls per user account.

# see what the registry reports before you hit the limit TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/node:pull" | jq -r .token) curl -sI -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/vnd.oci.image.index.v1+json" \ "https://registry-1.docker.io/v2/library/node/manifests/22" \ | grep -i ratelimit # ratelimit-limit: 100 # ratelimit-remaining: 7

The rate-limit headers are the honest source of truth, and they arrive before the failure. A script that checks ratelimit-remaining and fails the job early is cheaper than a build that dies twenty minutes later.

bash
# authenticate in CI without leaking the token in logs echo "$DOCKERHUB_TOKEN" | docker login --username "$DOCKERHUB_USER" --password-stdin # or keep a dedicated config dir for a single job DOCKER_CONFIG="$PWD/.docker-ci" \ sh -c 'echo "$TOKEN" | docker login -u "$USER" --password-stdin && docker buildx build --push .'

Use a read-only personal access token, not the account password, and scope it to public pulls. A token that can push to your namespace belongs in a separate secret used only by the release job.

Key Comparison Table

OptionCounterSetup costBest fit
Anonymous pullper public IPnonea laptop, never CI
docker login with a free accountper accountone secretnormal CI
Pull-through cache (registry:2 proxy)upstream once per imageone servicemany runners behind one network
Vendor to GHCR or ECRyour registry limitsa copy stepproduction clusters
Pin by digest and cache layersfewer manifestsnoneevery pipeline
SymptomLikely causeFirst check
toomanyrequests on one jobshared CI IP quotaratelimit-remaining header
Pulls work locally, fail in CIanonymous and shared egressdocker info for the username
Kubernetes ImagePullBackOff with the same textnode kubelet pulls anonymouslyimagePullSecrets on the pod
401 unauthorized after loginwrong registry host or token scopedocker login output, then ~/.docker/config.json
Limit reached with a logged-in useranother job on the same accountaccount-level usage, not IP
ApproachPrivate imagesAir-gappedMaintenance
registry:2 pull-through cacheyes, with credentialsnolow
Vendor into GHCRyesnomedium
Save and load tarballsyesyeshigh, manual
Vendor images into an internal registryyesyesmedium

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Authenticate once for the whole pipeline

Set the login as an explicit step before any build, and make it fail loudly. A silent docker login failure leaves the job anonymous and every later step suffers.

- name: Registry login env: DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} run: | test -n "$DOCKERHUB_TOKEN" echo "$DOCKERHUB_TOKEN" | docker login --username "$DOCKERHUB_USER" --password-stdin docker info --format '{{.Username}}'

docker info --format '{{.Username}}' prints the authenticated user, which is the one piece of evidence that the credential reached the daemon.

2. Pull-through cache for a fleet of runners

A registry that proxies Docker Hub stores each layer locally and serves it to every later request without counting against the upstream quota:

# compose for a small cache services: mirror: image: registry:2 environment: REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io ports: ["5000:5000"] volumes: ["mirror:/var/lib/registry"] volumes: { mirror: {} }

Point the daemon at it through /etc/docker/daemon.json:

{ "registry-mirrors": ["http://mirror.internal:5000"], "max-concurrent-downloads": 4 }

This covers the default registry only; images from ghcr.io or quay.io need their own proxy configuration. The first pull of a new tag still counts, so the cache helps most with a small set of heavily reused base images.

3. Vendor production images into a registry you control

For anything a cluster pulls, the dependency on Docker Hub is the problem, not the quota. Copy once, pin the digest, and let the cluster pull from your registry:

bash
docker pull node:22-bookworm-slim DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' node:22-bookworm-slim | cut -d@ -f2) docker tag node:22-bookworm-slim ghcr.io/acme/base/node:22-bookworm-slim docker push ghcr.io/acme/base/node:22-bookworm-slim echo "FROM ghcr.io/acme/base/node:22-bookworm-slim@${DIGEST}" > Dockerfile.base

A digest reference cannot be retagged upstream, and pulling from your own registry removes the shared-IP counter from the equation entirely.

4. Kubernetes: make the kubelet pull as you

A pod that pulls anonymously fails the same way, and the error hides in ImagePullBackOff:

bash
kubectl create secret docker-registry regcred \ --docker-server=https://index.docker.io/v1/ \ --docker-username="$DOCKERHUB_USER" \ --docker-password="$DOCKERHUB_TOKEN" kubectl patch deployment web -p \ '{"spec":{"template":{"spec":{"imagePullSecrets":[{"name":"regcred"}]}}}}'

Set imagePullPolicy: IfNotPresent for pinned tags so a node that already has the image never contacts the registry, and keep Always only for mutable tags you are deliberately testing. Each node counts once, so a 40-node cluster multiplies every pull by 40 unless the policy prevents it.

5. When you are already blocked

The quota is a rolling window; waiting it out is legitimate for a single job but wrong as a strategy. To recover immediately, pull through an authenticated account, copy the image from a machine that already has it, or retag a locally cached copy:

bash
docker save node:22-bookworm-slim | gzip > node-22.tar.gz # on the blocked host gunzip -c node-22.tar.gz | docker load

Keep the tarball path out of build contexts; a stray 200 MB file in the repository costs more than the pull it saved.

6. Reading a 401 instead of a 429

toomanyrequests is HTTP 429. A 401 after a successful login usually means the credential went to the wrong registry host or the token lost its scope. Check the stored config rather than guessing:

bash
cat ~/.docker/config.json | jq '.auths | keys' # ["https://index.docker.io/v1/"] for Docker Hub

The auths entry is a base64 user:token pair; decode it with Base64 Encoder / Decoder when you need to confirm which account a runner is using. To see the registry's own response to a manifest request, including the rate-limit headers, send it through HTTP header inspector with a token from the auth endpoint.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Logging in after the build step. BuildKit pulls base images during the build; a login placed later in the job changes nothing.
  • Using the account password. Docker Hub accepts it, then flags the login as suspicious; personal access tokens are the supported path since 2022.
  • One shared account for every job. The limit is per account, so a hundred parallel jobs on one login exhaust it just as fast as anonymous pulls on one IP.
  • Retry loops without backoff. Each retry is another manifest request; a tight loop burns whatever remains.
  • Assuming a mirror exempts you from Docker Hub terms. Pull-through caching is the sanctioned pattern; scraping a public mirror service is not, and it disappears without notice.
  • imagePullPolicy: Always with a pinned digest. It forces a registry round-trip on every pod start for an image that cannot change.
  • Forgetting docker logout on a shared runner. The next job inherits the credential, which is both a quota and a security problem.
  • Docker Desktop and CI on the same account. Desktop pulls and CI pulls share the account counter, so a developer pulling large images can starve the pipeline.

Primary references: Docker's usage and pull limits documents the current windows and the authenticated allowance, and the download rate limit page explains how the counter is keyed by IP and by account.

Official references

primary documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.