GitHub Actions Docker Action Fails - Docker Hub Pull Rate Limit (429)

A Docker-based action or a docker pull failed because Docker Hub rate-limited the unauthenticated pull from the shared runner IP. The image is fine; the anonymous quota was exhausted.

What this error means

A step that pulls a Docker Hub image fails with "toomanyrequests: You have reached your pull rate limit". It is intermittent because the limit is per-IP across many runners.

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

Common causes

Anonymous Docker Hub pulls are rate-limited

Unauthenticated pulls share a low per-IP limit. On busy shared runner IPs that limit is reached quickly, returning 429.

No mirror or registry auth configured

Pulling base images directly from Docker Hub without logging in, or without a pull-through mirror, leaves the job dependent on the anonymous quota.

How to fix it

Authenticate to Docker Hub

Log in with docker/login-action so pulls count against your account’s higher limit instead of the anonymous one.

- uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}
- run: docker pull node:20

Pull from a different registry or retry

1. Use the image from GHCR or a registry mirror that is not rate-limited.
2. Re-run the job; the per-IP limit usually clears shortly.
3. Cache built images so you do not re-pull base layers every run.

How to prevent it

• Authenticate to Docker Hub or use GHCR/a mirror for base images.
• Cache image layers to reduce repeated pulls.
• Treat 429 pull limits as transient and retry.

Related guides