# toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

- **ID:** `cicd/docker-pull-rate-limit`
- **Domain:** cicd
- **Category:** resource_error
- **Error Code:** `DOCKER_PULL_RATE_LIMIT`
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

Docker Hub pull rate limit exceeded (anonymous users: 100 pulls/6 hours, authenticated free users: 200 pulls/6 hours) due to high CI frequency or shared IP addresses.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0 | active | — | — |
| Docker 25.0 | active | — | — |
| Docker 26.0 | active | — | — |

## Workarounds

1. **Authenticate Docker Hub in CI: use 'docker login -u $DOCKER_USER -p $DOCKER_PAT' to increase the limit to 200 pulls/6 hours for free accounts or unlimited for Pro/Team accounts.** (90% success)
   ```
   Authenticate Docker Hub in CI: use 'docker login -u $DOCKER_USER -p $DOCKER_PAT' to increase the limit to 200 pulls/6 hours for free accounts or unlimited for Pro/Team accounts.
   ```
2. **Use a mirror registry like 'registry-mirror.example.com' or switch to Amazon ECR/GCR to avoid Docker Hub limits entirely. Example: 'docker pull registry-mirror.example.com/library/node:18'** (95% success)
   ```
   Use a mirror registry like 'registry-mirror.example.com' or switch to Amazon ECR/GCR to avoid Docker Hub limits entirely. Example: 'docker pull registry-mirror.example.com/library/node:18'
   ```

## Dead Ends

- **** — Passive waiting delays CI pipelines and doesn't solve the root cause; the limit will be hit again on the next build. (80% fail)
- **** — Changing platform doesn't bypass rate limits; each pull still counts against the same quota regardless of platform. (95% fail)