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

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 ""failed to pull image""?

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

How do I fix "failed to pull image"?