Dockerfile FROM base image "toomanyrequests" rate limit in CI

By Daniel Zoghalchali·Latchkey

The build failed while resolving the base image in FROM because anonymous Docker Hub pulls exceeded the rate limit. The same toomanyrequests error appears at build time, not just on an explicit docker pull.

What this error means

docker build fails at the FROM step with "toomanyrequests: You have reached your pull rate limit." after a run of anonymous pulls on the runner.

Step 1/8 : FROM node:20
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 exceeded the limit

Docker Hub limits unauthenticated pulls; a shared CI IP burns through the quota quickly and the FROM step is rejected.

The base image lives on a rate-limited registry

A free-tier Docker Hub base image is subject to limits that authenticated or mirrored pulls avoid.

How to fix it

Authenticate before the build

Log in so pulls count against a higher authenticated limit.

- run: echo "${{ secrets.DOCKERHUB_TOKEN }}" | docker login -u "${{ secrets.DOCKERHUB_USER }}" --password-stdin
- run: docker build -t app .

Use a mirror or a different registry

1. Configure a pull-through cache or registry mirror for base images.
2. Or host the base image on GHCR or ECR, which do not apply Hub limits.
3. Re-run the build once pulls are authenticated or mirrored.

How to prevent it

• Authenticate to Docker Hub before pulling base images in CI.
• Use a registry mirror or pull-through cache for base images.
• Move base images to a registry without anonymous pull limits.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation