failed to pull image (GitLab) CI/CD Origin: Build & delivery Last updated 25 Oct 2026

GitLab CI: ERROR: Job failed: failed to pull image "registry.example.com/app:latest" with specified policies [always]: access forbidden

The runner could not pull the job's Docker image — authentication, a wrong name or tag, or a registry rate limit.

Exact message you may see failed to pull image with specified policies [always]ERROR: Job failed: failed to pull imageaccess forbidden pulling image GitLab runnertoomanyrequests: You have reached your pull rate limitFailed to pull image
Explore the map of this error Full error map →
Seen on: GitLab CI Docker

Meaning

Private registries need credentials in the DOCKER_AUTH_CONFIG variable (or the runner's config). Docker Hub applies pull-rate limits to anonymous pulls from shared runners; use a registry mirror or authenticate. Tags may simply not exist.

Common causes

  • Private image without DOCKER_AUTH_CONFIG credentials
  • Wrong image name or missing tag
  • Docker Hub rate limit on shared runners
  • Expired token
  • Runner without network access to the registry

⚡ Quick fix

  1. Add DOCKER_AUTH_CONFIG (CI/CD variable) with the registry auth JSON
  2. Verify the image and tag exist: docker pull locally
  3. Use a dependency proxy or mirror to avoid rate limits

Detailed fix by platform

GitLab CI

  1. DOCKER_AUTH_CONFIG value: {"auths":{"registry.example.com":{"auth":"<base64 user:token>"}}}
  2. Use $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/node:20 for Docker Hub images

Code examples

Pull through the dependency proxy

yaml
build:
  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:20
  script: npm ci && npm test

How to diagnose

  1. Name — Image and tag correct?
  2. Auth — Credentials configured?
  3. Limit — Rate-limit message in the log?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Build & delivery. Errors that are often confused with or caused by this one (click to open):

Cannot connect to the Docker daemon (GitLab) — GitLab CI: Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running? (CI/CD)Cannot connect to the…Cannot perform an interactive login from a non TTY device — GitHub Actions: Error: Cannot perform an interactive login from a non TTY device (CI/CD)Cannot perform an int…denied — denied: requested access to the resource is denied (docker push) (Docker)deniedERROR: Job failed: exit code 1 — GitLab CI: ERROR: Job failed: exit code 1 (CI/CD)ERROR: Job failed: ex…execution took longer than 1h0m0s — GitLab CI: ERROR: Job failed: execution took longer than 1h0m0s seconds (CI/CD)execution took longer…Job depends on artifacts that have expired — GitLab CI: This job could not start because it could not retrieve the needed artifacts (dependencies: build). (CI/CD)Job depends on artifa…permission denied /var/run/docker.sock — Jenkins: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock (CI/CD)permission denied /va…Pipeline filtered out by workflow:rules — GitLab CI: No pipeline created — pipeline filtered out by workflow:rules / "The rules configuration prevented any jobs from being added to the pipeline" (CI/CD)Pipeline filtered out…failed to…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.