Docker "toomanyrequests" Docker Hub rate limit in CI

By Daniel Zoghalchali·Latchkey

Docker Hub enforces a per-IP pull limit for anonymous and free accounts. Shared CI egress IPs reach it quickly, and pulls then fail with toomanyrequests until the window resets.

What this error means

A pull or FROM fails with toomanyrequests: You have reached your pull rate limit. Authenticating or waiting for the window to reset clears it.

Error response from daemon: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

Common causes

Anonymous pulls over the limit

Unauthenticated pulls share a low per-IP cap, which busy CI exhausts fast.

Many jobs pulling the same base

Parallel jobs each pulling Docker Hub images multiply the request count against one IP.

How to fix it

Authenticate to Docker Hub

1. Log in so pulls count against your account at a higher limit.

- uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USER }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

Mirror or cache base images

1. Pull base images from GHCR/ECR mirrors instead of Docker Hub.
2. Cache layers between runs to avoid repeated pulls.

How to prevent it

• Authenticate and mirror base images off Docker Hub. Because the limit is transient and time-windowed, self-healing managed runners such as Latchkey auto-retry these 429s after a short backoff, so a momentary rate limit does not fail the job.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation