GitLab CI "toomanyrequests": Docker Hub rate limits and the dependency proxy

By Melih Toksari, developer of MergeBell · Updated · 5 min read

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 build or docker pull in the script pulls more, and fails with the same toomanyrequests text, often after 429 Too Many Requests.
  • On GitLab.com’s hosted runners, GitLab pulls image and services through 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 image and services.
  • Give services an alias. A service’s hostname comes from its image name, which now starts with GitLab’s address, so alias: redis keeps it reachable as redis.
  • 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_PREFIX uses 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 denied or 403: Access forbidden. Other credentials took over, such as a DOCKER_AUTH_CONFIG variable or the runner host’s /root/.docker/config.json. The job log’s Authenticating with credentials from line 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:

  1. Create a Docker Hub personal access token with read-only access.

  2. Encode your username and the token: printf "my_username:my_token" | openssl base64 -A.

  3. 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_policy is always. With pull_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’s image: pull_policy: works only if the runner allows that policy, in allowed_pull_policies or, without it, in pull_policy.

  • Use a registry mirror. Point the host’s Docker daemon at a pull-through cache with registry-mirrors in /etc/docker/daemon.json. A docker:dind service 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

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.