Docker Image Pull Policy "Never" - Image Not Present Locally in CI

By Kaveh Alemi·Latchkey

A never pull policy tells Docker to use only the local image and never pull. On an ephemeral CI runner with an empty image store, that image is not there - so the run fails. The mirror-image problem is always, which re-pulls every time and can hit rate limits.

What this error means

A docker run --pull=never or compose pull_policy: never fails with the image not found locally, because nothing built or loaded it on this runner. Or pull_policy: always causes redundant pulls that hit Docker Hub rate limits.

docker run / compose output

docker: Error response from daemon: No such image: myorg/api:1.4.2
# from: docker run --pull=never myorg/api:1.4.2  on a fresh runner (image never loaded)

Common causes

pull=never with an empty local store

Ephemeral CI runners start with no images. A never policy forbids pulling, so an image that was never built or loaded on this runner is simply absent.

The image was built in a different job

If the image was built in an upstream job and not shared (no push, no artifact load), the consuming job’s local store does not have it for a never policy.

pull=always causing rate-limited re-pulls

The opposite policy re-pulls on every run, which on a shared runner IP can trip Docker Hub rate limits.

How to fix it

Ensure the image is present, or let Docker pull when missing

Build/load the image first for never, or use the default missing policy that pulls only when absent.

Terminal

# default policy pulls only if not present:
docker run --pull=missing myorg/api:1.4.2
# for pull=never, load it first:
docker load -i image.tar
docker run --pull=never myorg/api:1.4.2

Set a sensible pull policy in compose

Use missing to avoid both the "not present" failure and needless re-pulls.

docker-compose.yml

services:
  api:
    image: myorg/api:1.4.2
    pull_policy: missing

How to prevent it

Use missing pull policy unless you control image presence explicitly.
Build/load the image in the same job that runs it for never.
Authenticate to Docker Hub if you rely on always to avoid rate limits.

Frequently asked questions

What causes "pull policy "never" no local image"?

Ephemeral CI runners start with no images. A never policy forbids pulling, so an image that was never built or loaded on this runner is simply absent.

How do I fix pull policy "never" no local image?

Build/load the image first for never, or use the default missing policy that pulls only when absent.