Docker "pull policy always but offline" in CI

By Kaveh Alemi·Latchkey

With --pull always (or a compose pull_policy: always), the daemon contacts the registry on every run even if the image is cached locally. On an offline or air-gapped runner that contact fails, and the run aborts even though a usable image already sits in the local store.

What this error means

A docker run --pull always (or compose up) fails with a network/registry error while a locally cached image of the same tag is present.

docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io: no such host.

Common causes

Pull-always on an offline runner

The policy forces a registry round-trip the air-gapped or network-restricted runner cannot complete.

No registry mirror reachable

A restricted network with no reachable mirror has nothing for the always-pull to hit.

How to fix it

Use the cached image with pull missing/never

1. Switch the policy to missing (pull only if absent) or never when offline.

docker run --pull missing myorg/app:ci
# fully offline with a pre-loaded image:
docker run --pull never myorg/app:ci

Pre-load the image before going offline

1. Save the image to a tar in a connected step and load it on the offline runner.

docker save myorg/app:ci -o app.tar
docker load -i app.tar
docker run --pull never myorg/app:ci

How to prevent it

• On offline runners, set pull policy to missing or never.
• Pre-load required images via docker save/docker load.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation