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

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.

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.

image: registry.example.com/app:1.4.2

Beat rate limits with authenticated/mirrored pulls

1. Authenticate pulls so they use a higher rate limit.
2. Use a pull-through registry mirror for popular base images.
3. 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.

Related guides