Docker "Unable to find image locally" Then Pull Fails in CI

By Daniel Zoghalchali·Latchkey

"Unable to find image locally" is just Docker saying it has to pull the image first. It only matters when the pull that follows then fails - that second error is the real problem.

What this error means

docker run prints Unable to find image 'X' locally, attempts a pull, and either succeeds (normal) or fails with an auth/manifest/format error that is the actual blocker.

docker run output

Unable to find image 'myorg/api:latest' locally
docker: Error response from daemon: pull access denied for myorg/api ...

Common causes

The image is simply not cached on this runner

Ephemeral CI runners start with an empty image store, so any first use prints this line before pulling. On its own it is expected behavior.

The follow-up pull fails

When the line is followed by an error, the cause is whatever the pull hit: a typo, a private image with no login, a missing tag, or a rate limit.

How to fix it

Read the line after the "Unable to find" message

Treat the pull error as the real failure and fix that - auth, name, or tag.

Terminal

# pre-pull explicitly to separate the pull error from the run
docker pull myorg/api:1.4.2
docker run --rm myorg/api:1.4.2

Pre-pull or cache base images

Authenticate before the first pull so private images resolve.
Pin exact tags/digests so the pull is deterministic.
Cache or mirror frequently-used images to avoid rate limits.

How to prevent it

Do not treat the "Unable to find image locally" line alone as an error.
Pre-pull and authenticate so the implicit pull never surprises you.

Frequently asked questions

What causes ""Unable to find image locally""?