How to fix toomanyrequests: You have reached your pull rate limit in Kubernetes

What this error means

The "toomanyrequests: You have reached your pull rate limit" error means you've exceeded Docker Hub's rate limiting policy for image pulls. Docker Hub limits anonymous pulls to 100 per 6 hours per IP address, and authenticated free users to 200 per 6 hours. In Kubernetes environments, this error frequently occurs because multiple pods across many nodes share the same egress IP address, rapidly consuming the rate limit. CI/CD pipelines and auto-scaling workloads are particularly susceptible since they pull images frequently during deployments and scaling events. The error manifests as HTTP 429 (Too Many Requests) and causes pods to enter ImagePullBackOff state until the rate limit window resets.

Typical symptoms

• Pods stuck in ImagePullBackOff with 429 error code
• Docker pull fails with "toomanyrequests" message
• Works locally but fails in CI/CD or Kubernetes
• Intermittent failures during high-volume deployments
• All pods on cluster fail to pull simultaneously
• Pulls succeed early in day, fail later (quota exhausted)

Common causes

1. Unauthenticated pulls hitting 100/6hr anonymous limit
2. Multiple containers pulling from shared IP exhaust quota quickly
3. Free Docker account authentication only provides 200/6hr limit
4. Shared cloud infrastructure (managed Kubernetes) multiplies pull counts
5. Expired or invalid Docker Hub credentials causing unauthenticated fallback

How to fix "toomanyrequests: You have reached your pull rate limit"

# Login locally
docker login

# Check remaining pulls
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/manifests/latest 2>&1 | grep -i ratelimit

RateLimit-Limit: 200
RateLimit-Remaining: 195

# Create docker-registry secret
kubectl create secret docker-registry dockerhub-secret \
  --docker-server=docker.io \
  --docker-username=<YOUR_USERNAME> \
  --docker-password=<YOUR_ACCESS_TOKEN> \
  --docker-email=<YOUR_EMAIL>

# Patch default ServiceAccount
kubectl patch serviceaccount default -p \
  '{"imagePullSecrets": [{"name": "dockerhub-secret"}]}'

spec:
  template:
    spec:
      imagePullSecrets:
      - name: dockerhub-secret
      containers:
      - name: app
        image: myrepo/myapp:latest

# Re-authenticate to apply new limits
docker logout && docker login

# Verify unlimited status
curl -s "https://hub.docker.com/v2/users/<USERNAME>" | jq '.is_paid'

# Run official pull-through cache
docker run -d \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  --name registry-proxy \
  registry:2

# Configure Docker daemon to use mirror
cat > /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": ["http://localhost:5000"]
}
EOF

# Reload Docker
systemctl reload docker

docker pull mirror.gcr.io/library/ubuntu:latest
docker pull mirror.gcr.io/library/nginx:alpine

# GitHub Actions example
name: Build
on: push

jobs:
  build-1:
    runs-on: ubuntu-latest
    steps:
      - uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USER_1 }}
          password: ${{ secrets.DOCKERHUB_TOKEN_1 }}
      - run: docker build . -t myapp:v1

  build-2:
    runs-on: ubuntu-latest
    steps:
      - uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USER_2 }}
          password: ${{ secrets.DOCKERHUB_TOKEN_2 }}
      - run: docker build . -t myapp:v2

# Pin specific versions (better caching)
FROM ubuntu:22.04

# NOT this (always re-pulls):
FROM ubuntu:latest

# GitHub Actions with layer caching
- uses: docker/build-push-action@v4
  with:
    context: .
    cache-from: type=registry,ref=myregistry/myapp:buildcache
    cache-to: type=registry,ref=myregistry/myapp:buildcache,mode=max

Advanced notes

regctl image ratelimit nginx:latest

Frequently asked questions

What does "toomanyrequests: You have reached your pull rate limit" mean?

The "toomanyrequests: You have reached your pull rate limit" error means you've exceeded Docker Hub's rate limiting policy for image pulls. Docker Hub limits anonymous pulls to 100 per 6 hours per IP address, and authenticated free users to 200 per 6 hours. In Kubernetes environments, this error frequently occurs because multiple pods across many nodes share the same egress IP address, rapidly consuming the rate limit.

How do I fix "toomanyrequests: You have reached your pull rate limit"?

This error occurs when you exceed Docker Hub's rate limits for image pulls. Fix it by authenticating to increase limits, using registry mirrors, or upgrading to a Docker paid subscription.

What causes "toomanyrequests: You have reached your pull rate limit"?

Unauthenticated pulls hitting 100/6hr anonymous limit Multiple containers pulling from shared IP exhaust quota quickly Free Docker account authentication only provides 200/6hr limit

Is the "toomanyrequests: You have reached your pull rate limit" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• ImagePullBackOff

  How to fix "ImagePullBackOff" in Kubernetes

  HIGH

• imagePullPolicy Never

  How to fix imagePullPolicy Never issues

  MEDIUM

• Failed to pull image: secret not found

  How to fix "Failed to pull image: secret not found" in Kubernetes

  HIGH

• ImagePullBackOff

  How to fix "ImagePullBackOff" in Kubernetes

  HIGH

• upstream connect error or disconnect/reset before headers. reset reason: overflow

  How to fix "upstream connect error or disconnect/reset before headers" in Kubernetes

  HIGH

• ArgoCD degraded

  How to fix "ArgoCD degraded" in Kubernetes

  HIGH

Official resources & further reading

• 📚Kubernetes Official Documentation
• 📖
  K8s: Images guide(Official Docs)
• 📖
  Docker Hub: Rate limiting(Official Docs)
• 💬
  SO: Docker rate limit(Stack Overflow)