GitLab CI "WARNING: Failed to pull image ... will be built" in CI

By Kaveh Alemi·Latchkey

The runner failed to pull the requested image and, depending on its pull_policy, either uses an existing local copy or fails the job. The warning points at a transient registry issue or a missing image.

What this error means

The log shows "WARNING: Failed to pull image with policy ...: ... falling back to local" or, if no local image exists, "ERROR: failed to pull image".

WARNING: Failed to pull image with policy "always": Error response from daemon: received unexpected HTTP status: 503 Service Unavailable

Common causes

A transient registry outage

A 5xx from the registry makes the pull fail; with if-not-present the runner may use a stale local image, hiding the problem.

pull_policy that masks missing images

An always policy fails loudly, while if-not-present silently runs an outdated local image when the pull fails.

How to fix it

Retry transient pulls and set an explicit policy

1. Set the runner or job pull_policy to the behavior you want.
2. For a flaky registry, retry the job so a momentary 5xx clears.
3. Confirm the intended image version actually runs.

# config.toml on the runner
[runners.docker]
  pull_policy = ["always"]

Use a reliable mirror or pin a digest

Pin the image by digest and consider a registry mirror so a single outage does not block all jobs.

build:
  image: registry.example.com/app@sha256:<digest>

How to prevent it

• Choose a pull_policy deliberately so you do not run stale images.
• Pin images by digest for reproducibility.
• Add a registry mirror to absorb transient outages.

Frequently asked questions

Related guides

References

• GitHub Actions documentation