highFoundationSymptom-first#registry#rate-limit#docker-hub#authentication

Docker Hub rate limit — anonymous or free-tier pull limit exceeded

docker pull returns 'You have reached your pull rate limit'

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • docker pull returns 'You have reached your pull rate limit'
  • docker run fails with toomanyrequests: You have reached your pull rate limit
  • Container image pull fails intermittently during CI/CD builds

Docker Hub anonymous limits are 100 pulls per 6 hours per IP. Authenticated (free) limits are 200 pulls per 6 hours per account. Use a pull-through cache for CI/CD-heavy workloads.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Rate limit headers

    curl -sI https://hub.docker.com/v2/repositories/library/alpine/tags/latest | grep -i ratelimit

  • Docker Hub login status

    docker login --username <USER> --password-stdin <<< <TOKEN> 2>&1 | head -1

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • docker info shows no Registry Username
  • toomanyrequests error on docker pull from Docker Hub
  • CI pipeline pulls many images without authenticating

Confirm before fixing

docker info 2>/dev/null | grep Registry
READ

Check Docker Hub authentication status

Fix

echo $DOCKERHUB_TOKEN | docker login --username <USER> --password-stdin
CHANGE

Authenticate to Docker Hub to get higher rate limits

Expected: Login Succeeded

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
docker info 2>/dev/null | grep -i 'Registry\|Username'
READ

Check Docker Hub login status

2
curl -sI -u <USER>:<TOKEN> https://registry-1.docker.io/v2/ | grep -i ratelimit
READ

Check remaining pull quota

3
echo $DOCKERHUB_TOKEN | docker login --username <USER> --password-stdin
CHANGE

Authenticate to Docker Hub

4
docker pull <PRIVATE_REGISTRY>/<IMAGE>:<TAG>
CHANGE

Pull from a mirror if rate limits persist

Prevention

  • Authenticate to Docker Hub in all CI/CD pipelines: docker login with a token.
  • Mirror frequently-used images to a private registry or pull-through cache (e.g., Harbor, ECR).
  • Pin image tags to avoid repeated pulls of :latest.
  • Monitor pull counts via Docker Hub API or registry logs.

Related runbooks

Same stack, same failure family — worth a skim.

ImagePullBackOff / ErrImagePull — pod can't fetch its imagehigh

Pod stuck in ImagePullBackOff or ErrImagePull

KubernetesFoundation3 causes
Open runbook
Exec format error — image built for wrong CPU architecturehigh

exec format error when starting container on ARM host pulling amd64 image

DockerIntermediate2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.