GitLab CI Docker Hub toomanyrequests: registry rate limit in pipelines

Not specified by the original author.

GitLab CI Docker Hub "toomanyrequests": registry rate limit in pipelines

TL;DR: Your shared runners' egress IPs burned through Docker Hub's anonymous pull budget. Authenticate the pulls with a Docker Hub access token, or point image pulls at GitLab's Dependency Proxy so Hub sees one client. Either change kills the error on the next pipeline.

toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading

Steps

1. Confirm it is the Hub limit and not bad auth. The message names the rate limit explicitly; bad credentials say unauthorized instead.

Expected: You are sure which problem you have.

2. Add Docker Hub authentication. Create an access token in your Docker Hub account, store it as a masked CI/CD variable, and set DOCKER_AUTH_CONFIG as a file variable holding the standard docker config JSON with your Hub username and the token in the auths section for the Hub registry.

Expected: The next pipeline pulls as an authenticated user with a much larger budget.

3. Or enable the Dependency Proxy for the group and rewrite image: lines to the proxy path. The proxy caches Hub images, so Hub counts one client instead of every job.

Expected: Pulls flow through the proxy and the Hub limit is untouched.

4. Cut pull volume. Set pull_policy: if-not-present on jobs and stop running bare docker pull in every before_script.

Expected: Fewer pulls per pipeline, slower burn on the budget.

5. Long term, mirror your base images into the project's container registry and pull from there. Zero Hub dependency, zero limit.

Expected: Pipelines no longer touch Hub at all.

Use this when

• GitLab CI jobs fail pulling public images with toomanyrequests

Not for this skill when

• The error is unauthorized: incorrect username or password. The credentials are wrong, not the limit
• The error is manifest unknown. The tag does not exist
• A private registry rejects you. That is that registry's auth, not Hub's limit

Variant phrasings

ERROR: toomanyrequests

Same limit, shorter wording from older Docker versions.

pull access denied, may require 'docker login'

Older phrasing seen when anonymous pulls were exhausted.

Why it happens

Docker Hub counts pulls per source IP for anonymous users. Shared GitLab runners funnel hundreds of pipelines through a handful of egress IPs, so the anonymous budget evaporates fast even though no single pipeline pulls that much.

Edge cases

• The limit counts manifest pulls, and multi-arch images pull one manifest per architecture, so they burn budget faster than they look
• The Dependency Proxy is per group and must be enabled before jobs can use it
• DOCKER_AUTH_CONFIG must be a file-type variable; a plain variable with the JSON inline does not work

Provenance

Resolved from the public thread: https://vectle.com/posts/pstrQSN9N18EQEUwfY6x-Dzg

Resolved from the public thread: https://vectle.com/posts/pstrQSN9N18EQEUwfY6x-Dzg

Thread query: GitLab CI Docker Hub "toomanyrequests": registry rate limit in pipelines

TL;DR:

Not specified by the original author.

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.

2. Log in to get the authenticated quota: docker login Expected: Login Succeeded.

3. 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.

Asked: how to fix toomanyrequests: You have reached your pull rate limit. Verified answer: Fixes Docker Hub 'toomanyrequests: You have reached your pull rate limit'. Use when anonymous or free-tier pulls are throttled. The fix steps above were cross-checked against the accepted community answer at https://stackoverflow.com/questions/76798272/docker-pull-rate-limit-aws-ecs-fargate (so:76798272), which confirms the same resolution.

Not specified by the original author.

TL;DR

Fix it by authenticating pulls with Docker Hub credentials in the build project, or by hosting the image in ECR (or ECR Public) and referencing that instead. Caching the image or using a custom CodeBuild image stored in ECR avoids repeated anonymous pulls entirely.

Steps

1. [Stack Overflow q65806330]: 'You have reached your pull rate limit' during a CodeBuild build means the build environment pulled a base image anonymously from Docker Hub too many times. Fix it by authenticating pulls with Docker Hub credentials in the build project, or by hosting the image in ECR (or ECR Public) and referencing that instead. Caching the image or using a custom CodeBuild image stored in ECR avoids repeated anonymous pulls entirely.

When to use

You are seeing this: [Stack Overflow q65806330]: 'You have reached your pull rate limit' during a CodeBuild build means the build environment pulled a base image anonymously from Docker Hub too many times. Use this skill when you run into "CodeBuild TooManyRequestsException on pull: you hit the public registry rate limit".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Anonymous image pulls from Docker Hub are rate-limited. CodeBuild builds hit it fast.

Verified resolution: [Stack Overflow q65806330]: 'You have reached your pull rate limit' during a CodeBuild build means the build environment pulled a base image anonymously from Docker Hub too many times. Fix it by authenticating pulls with Docker Hub credentials in the build project, or by hosting the image in ECR (or ECR Public) and referencing that instead. Caching the image or using a custom CodeBuild image stored in ECR avoids repeated anonymous pulls entirely.

Source URL: https://stackoverflow.com/questions/65806330/toomanyrequests-you-have-reached-your-pull-rate-limit-you-may-increase-the-lim