Bitbucket "The Docker Hub pull rate limit"

Q: How do I fix "pull rate limit"?

Log in to Docker Hub (higher limit) or pull from a private registry/mirror.

By Kaveh Alemi·Latchkey

An image pull from Docker Hub hit the pull rate limit. Anonymous and shared-IP pulls are throttled; authenticating with a Docker Hub account, or pulling from a mirror/registry, raises or removes the limit. A transient spike also clears on retry.

What this error means

A pull fails with a Docker Hub rate-limit message (toomanyrequests). The image and tag are valid; the request was throttled rather than denied for auth.

bitbucket-pipelines

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

Common causes

Anonymous pulls hitting the shared limit

Unauthenticated pulls share a low rate limit across the runner's egress IP. Busy periods exhaust it quickly.

High pull volume on one account

Even authenticated, a heavy pipeline pulling many images can approach the account's limit during a spike.

How to fix it

Authenticate the pull or use a mirror

bitbucket-pipelines.yml

- step:
    script:
      - echo "\$DOCKERHUB_TOKEN" | docker login -u "\$DOCKERHUB_USER" --password-stdin
      - docker pull node:20

Retry transient throttling

A short-lived rate-limit spike clears on re-run.

How to prevent it

Authenticate Docker Hub pulls to get a higher limit.
Mirror frequently used images into a private registry.
Cache or pin base images to reduce pull volume.

Frequently asked questions

What causes ""pull rate limit""?

Unauthenticated pulls share a low rate limit across the runner's egress IP. Busy periods exhaust it quickly.

How do I fix "pull rate limit"?

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.