CircleCI "pull access denied" / Docker Hub rate limit in CI

By Kaveh Alemi·Latchkey

Pulling a Docker image failed: "pull access denied" means the image is private or misnamed, while "toomanyrequests" means Docker Hub throttled anonymous pulls. Authenticating fixes both classes.

What this error means

A pull fails with "Error response from daemon: pull access denied for X" or "toomanyrequests: You have reached your pull rate limit".

Error response from daemon: pull access denied for myorg/app, repository
does not exist or may require 'docker login': denied: requested access to
the resource is denied

Common causes

The image is private or misnamed

Without credentials, a private repository looks non-existent and the daemon denies the pull.

Anonymous Docker Hub rate limit

Unauthenticated pulls share a low rate limit; busy CI exhausts it and gets "toomanyrequests".

How to fix it

Authenticate the image pull

1. Store registry credentials in a context or env vars.
2. Provide auth on the docker image entry.
3. Re-run so the pull is authenticated and not rate-limited.

jobs:
  build:
    docker:
      - image: myorg/app:1.2.3
        auth:
          username: $DOCKERHUB_USER
          password: $DOCKERHUB_PASS

Use a mirror or pre-pulled base

Pull from an authenticated registry or a CircleCL image to avoid anonymous Hub limits.

How to prevent it

• Authenticate all image pulls in CI.
• Use a private registry or mirror for hot base images.
• Pin image tags so pulls are cacheable and predictable.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation