GitLab CI "Job failed: failed to pull image" (Runner)

By Daniel Zoghalchali·Latchkey

The runner could not pull the container image for your job or a service. The tag is wrong, the registry needs credentials, or the pull was rate-limited - the GitLab equivalent of an ImagePullBackOff.

What this error means

The job fails during preparation while pulling the image: with "manifest unknown", "not found", or "toomanyrequests". Your script never runs because there is no container.

gitlab-ci

ERROR: Job failed: failed to pull image "registry.example.com/app:latst"
with specified policies [always]: Error response from daemon:
manifest for registry.example.com/app:latst not found: manifest unknown

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

.gitlab-ci.yml

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

Common causes

Wrong image name or tag

A typo in the repository or tag (latst for latest), or a tag never pushed, yields "manifest unknown"/"not found".

Registry rate limit

Anonymous Docker Hub pulls are rate-limited ("toomanyrequests"). Under load the pull is throttled and fails transiently.

How to fix it

Pin a correct, existing tag

Use a tag you know exists in the registry; verify with a manual pull.

.gitlab-ci.yml

image: registry.example.com/app:1.4.2

Beat rate limits with authenticated/mirrored pulls

Authenticate pulls so they use a higher rate limit.
Use a pull-through registry mirror for popular base images.
Retry the job; transient rate-limit/network pull failures usually clear.

How to prevent it

Pin image tags and verify they exist before merging.
Use authenticated pulls or a mirror to avoid rate limits.
Configure registry credentials for any private base image.

Frequently asked questions

What causes GitLab CI "Job failed: failed to pull image" (Runner)?

There are 2 common causes: wrong image name or tag and registry rate limit. A typo in the repository or tag (latst for latest), or a tag never pushed, yields "manifest unknown"/"not found".

How do I fix GitLab CI "Job failed: failed to pull image" (Runner)?

There are 2 fixes depending on which cause you have: pin a correct, existing tag and beat rate limits with authenticated/mirrored pulls. Work through them in order, since the first is the most common.

What does GitLab CI "Job failed: failed to pull image" (Runner) actually mean?

The job fails during preparation while pulling the image: with "manifest unknown", "not found", or "toomanyrequests".

How do I stop GitLab CI "Job failed: failed to pull image" (Runner) happening again?

Pin image tags and verify they exist before merging. The prevention section lists 3 changes that keep it from recurring.

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.

References

GitHub Actions documentation