GitLab CI "toomanyrequests": Docker Hub rate limits and the dependency proxy
Short answer
"toomanyrequests: You have reached your unauthenticated pull rate limit" comes from Docker Hub, not GitLab: the job's image, its services or a docker build pulled more than Docker Hub allows. On GitLab.com's hosted runners, image and services come through a Google Cloud cache, so it's usually a docker build or docker pull in the script. Without a login, Docker Hub allows 100 pulls per six hours for each IPv4 address or IPv6 /64 subnet, and 200 for a free Docker Personal account. The usual fix is GitLab's dependency proxy, on every tier: in a project that belongs to a group, put the dependency proxy's image prefix variable in front of Docker Hub images, and GitLab caches them, so repeat pulls don't count. Or log in to Docker Hub, with a DOCKER_AUTH_CONFIG variable for images and services and docker login in the script, or use a registry mirror on your own runners.
A job fails before its script starts, and its log says:
WARNING: Failed to pull image with policy "always": Error response from daemon: toomanyrequests: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit
Other versions of the message say toomanyrequests: You have reached your pull rate limit, sometimes followed by You may increase the limit by authenticating and upgrading. Either way, Docker Hub refused the pull, not GitLab. Here’s how to stay under its limits with GitLab 19.5.
Docker Hub’s limits
| Who pulls | Pulls per six hours |
|---|---|
| Not logged in | 100 for each IPv4 address or IPv6 /64 subnet |
| Docker Personal, free | 200 |
| Docker Pro, Team, Business | Unlimited, with fair use |
- Each job pulls its image and every service. A
docker buildordocker pullin the script pulls more, and fails with the sametoomanyrequeststext, often after429 Too Many Requests. - On GitLab.com’s hosted runners, GitLab pulls
imageandservicesthrough Google Cloud’s pull-through cache, which it says keeps them clear of the limits. Images pulled inside the job, such as a Docker-in-Docker or Kaniko build’s base images, still count. - Without a login, the limit is per address, so jobs on runners that share one, behind the same NAT gateway for example, use it up together.
- Docker Hub counts GET requests for an image’s manifest. HEAD requests, which only check whether an image changed, don’t count.
To see what’s left for a runner’s address, run this job on it. It checks with a HEAD request, so it doesn’t use a pull, and it gets its own image through the dependency proxy, below; outside a group, use plain alpine:latest:
docker-hub-limit:
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine:latest
script:
- apk add --no-cache curl jq
- TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
- curl -s --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest | grep -i ratelimit || echo "No rate limit headers"
ratelimit-limit: 100;w=21600 means 100 pulls per 21,600 seconds, six hours; ratelimit-remaining is what’s left. Docker Hub sends no such headers where no limit applies.
Pull through the dependency proxy
GitLab’s dependency proxy, on every tier, caches Docker Hub images for a group. Put a predefined variable in front of Docker Hub images:
default:
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:22
test:
services:
- name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/redis:7
alias: redis
script:
- npm test
- The runner logs in to the proxy for you, for
imageandservices. - Give services an alias. A service’s hostname comes from its image name, which now starts with GitLab’s address, so
alias: rediskeeps it reachable asredis. - Cached images rarely count against the limit. GitLab keeps each image, checks Docker Hub with a HEAD request when it’s pulled again, and downloads it only if it changed.
- The variable points at the top-level group.
CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIXuses the project’s own subgroup instead. - Only Docker Hub images go through the proxy.
When a pull through the proxy fails:
not found, or a 404. The project is in a personal namespace, so the variable points at a namespace with no dependency proxy; the proxy is off for the group; or the person who runs the pipeline doesn’t have at least the Guest role in the group. A group Owner turns the proxy on under Settings › Packages and registries › Dependency Proxy. It’s on by default.HTTP Basic: Access deniedor403: Access forbidden. Other credentials took over, such as aDOCKER_AUTH_CONFIGvariable or the runner host’s/root/.docker/config.json. The job log’sAuthenticating with credentials fromline shows which.- SAML SSO. When the group enforces SSO, the person who runs the pipeline must have signed in through SSO before the proxy serves their jobs.
Docker builds through the proxy
In a Docker-in-Docker build, the dind service’s Docker daemon pulls the FROM images with the job’s Docker login, so log in to the proxy and pass the prefix to the Dockerfile:
build:
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:24.0.5-cli
services:
- name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:24.0.5-dind
alias: docker
variables:
DOCKER_TLS_CERTDIR: "/certs"
before_script:
- echo "$CI_DEPENDENCY_PROXY_PASSWORD" | docker login "$CI_DEPENDENCY_PROXY_SERVER" -u "$CI_DEPENDENCY_PROXY_USER" --password-stdin
script:
- docker build --build-arg BASE="$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX" -t my-app .
ARG BASE=docker.io/library
FROM ${BASE}/node:22
The default keeps the Dockerfile working on your computer. The dind setup itself is in Cannot connect to the Docker daemon.
Give the proxy a Docker Hub login
By default, the proxy pulls from Docker Hub without a login. Since GitLab 17.11, a group Owner can add one under Settings › Packages and registries › Dependency Proxy, in Docker Hub authentication: your Docker Hub username as Identity and a personal access token as Secret. The proxy’s pulls then count against that account. For a Docker Hub organization, use its name and an organization access token.
Or log in to Docker Hub
Without a group, log the runner in to Docker Hub:
-
Create a Docker Hub personal access token with read-only access.
-
Encode your username and the token:
printf "my_username:my_token" | openssl base64 -A. -
In Settings › CI/CD › Variables, add a variable named
DOCKER_AUTH_CONFIG:{ "auths": { "https://index.docker.io/v1/": { "auth": "bXlfdXNlcm5hbWU6bXlfdG9rZW4=" } } }
The runner uses it for the job’s image and services, and the job log says Authenticating with credentials from $DOCKER_AUTH_CONFIG. A protected variable is there only in pipelines for protected branches and tags: see GitLab CI/CD variable empty.
For docker pull and docker build in the script, log the Docker client in too, with the username and token in their own variables:
before_script:
- echo "$DOCKER_HUB_TOKEN" | docker login -u "$DOCKER_HUB_USER" --password-stdin
Logged-in pulls count against the account, 200 per six hours on a free Personal account, shared by every job that uses it. Paid Docker plans have no pull limit, subject to fair use.
On your own runners
-
Reuse images the host has. The Docker executor’s default
pull_policyisalways. Withpull_policy = ["always", "if-not-present"]in[runners.docker], a failed pull falls back to the host’s copy;["if-not-present"]pulls only when the host has none. A job’simage: pull_policy:works only if the runner allows that policy, inallowed_pull_policiesor, without it, inpull_policy. -
Use a registry mirror. Point the host’s Docker daemon at a pull-through cache with
registry-mirrorsin/etc/docker/daemon.json. Adocker:dindservice starts with its own settings, so give it the mirror too:services: - name: docker:24.0.5-dind command: ["--registry-mirror", "https://registry-mirror.example.com"]
You can also copy the images you use into your project’s container registry, with a scheduled job, and use $CI_REGISTRY_IMAGE/node:22 in jobs: the runner pulls from the project’s own registry with the job’s credentials. If that pull says denied, see GitLab container registry “denied”.
On your phone
MergeBell shows a job’s log live, so the toomanyrequests line is there as soon as the runner writes it, and Retry reruns the job on the free tier. Docker Hub counts pulls over six hours, so a retry can work with no change once pulls free up; a new image prefix in .gitlab-ci.yml needs a new commit. More in how to retry a failed GitLab pipeline.
Frequently asked questions
Why does my GitLab CI job fail with "toomanyrequests: You have reached your pull rate limit"?
Docker Hub refused another pull. Without a login, it allows 100 pulls per six hours for each IPv4 address or IPv6 /64 subnet, so jobs on runners that share an address use them up together; a free Docker Personal account gets 200. Each job pulls its image and services, and a docker build pulls its base images too; on GitLab.com's hosted runners, GitLab caches image and services, so the limit usually hits builds and pulls in the script. Pull through GitLab's dependency proxy, log in to Docker Hub, or retry once pulls free up.
How do I use the GitLab dependency proxy in CI?
Put ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/ in front of Docker Hub images, such as image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:22, and give services an alias, such as alias: redis. The runner logs in to the proxy automatically. The project must belong to a group, the proxy must be on for that group, as it is by default, and the person who runs the pipeline needs at least the Guest role in the group.
Does the GitLab dependency proxy avoid Docker Hub rate limits?
Largely. GitLab caches each image. When it's pulled again, GitLab checks Docker Hub with a HEAD request for the manifest, which Docker Hub doesn't count, and downloads it again only if the image changed. By default the proxy pulls from Docker Hub without a login; since GitLab 17.11, a group Owner can add a Docker Hub username and access token under Settings › Packages and registries › Dependency Proxy.
How do I log in to Docker Hub in GitLab CI?
For the job's image and services, add a CI/CD variable named DOCKER_AUTH_CONFIG with an auths entry for https://index.docker.io/v1/, whose auth value is the Base64 of your Docker Hub username, a colon and an access token. For docker pull and docker build in the script, run docker login with the same username and token, because the Docker client in the job doesn't read that variable.
Can a project in my personal namespace use the dependency proxy?
Not with the predefined variables: they point at your personal namespace, which has no dependency proxy, so pulls fail with a not found error. You can write a group's prefix instead, such as gitlab.com:443/my-group/dependency_proxy/containers/node:22, if the person who runs the pipeline has at least the Guest role in that group. Or move the project into a group, or log in to Docker Hub.
Sources
- GitLab docs — Dependency proxy for container images
- Docker docs — Docker Hub usage and limits
- GitLab docs — Access an image from a private container registry (DOCKER_AUTH_CONFIG)
- GitLab docs — Enable registry mirror for the docker:dind service
- GitLab Runner docs — Configure how runners pull images
- GitLab blog — Docker Hub rate limits and GitLab CI/CD (hosted runners' cache)
- GitLab source — the dependency proxy's group check
Checked against these pages on 10 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.