CircleCI Docker Image Pull Rate Limit Exceeded

By Daniel Zoghalchali·Latchkey

Docker Hub rate-limits anonymous pulls. When CircleCI spins up a job using a Docker Hub image without authentication, a busy window can return a rate-limit error and fail the job.

What this error means

The job fails during environment spin-up with a Docker Hub toomanyrequests / pull rate limit message.

Error response from daemon: toomanyrequests: You have reached your
pull rate limit. https://www.docker.com/increase-rate-limit

Common causes

Anonymous Docker Hub pulls

Unauthenticated pulls share a low rate-limit pool that fills during busy periods.

Transient rate-limit window

A spike of pulls can momentarily exceed the limit even when usage is normally fine.

How to fix it

Authenticate the image pull

Provide Docker Hub credentials so the pull uses a higher authenticated limit.

jobs:
  build:
    docker:
      - image: cimg/node:20.11
        auth:
          username: $DOCKERHUB_USER
          password: $DOCKERHUB_PASS

Use registry images or a mirror

1. Prefer CircleCI convenience images or your own registry.
2. Mirror frequently used images to a registry you control.
3. Re-run the job; the limit usually clears within minutes.

How to prevent it

• Authenticate Docker Hub pulls in CI.
• Mirror hot images to a private registry.
• Avoid unauthenticated public pulls for critical jobs.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation