16.4.1.2 Compose Image Reference Error

A Compose image reference error occurs when a service's image value cannot actually be resolved to a real, pullable image, whether due to a typo in the repository name, an incorrect tag, missing registry authentication, or an ambiguous reference that resolves differently than intended, and these errors generally surface clearly during docker compose up but require checking several distinct possible causes to resolve efficiently.

Basic typo and tag errors

The most common version of this error is a straightforward typo in the image name or tag, producing a clear "not found" or "manifest unknown" error directly naming the reference that could not be resolved:

services:
  api:
    image: my-api:1.4.0

Error response from daemon: manifest for my-api:1.4.0 not found: manifest unknown

This error means the registry was reached successfully but does not have an image matching exactly that repository and tag combination, which is different from a connectivity failure; double-checking the exact, correct tag, including whether it actually exists in the registry at all, resolves this directly:

docker pull my-api:1.4.0

Attempting the pull directly, outside of Compose, often produces a more specific or differently worded error that can clarify exactly what went wrong.

Missing registry prefix for non-Docker-Hub images

An image hosted on a registry other than Docker Hub needs its full registry hostname included in the reference; omitting it causes Docker to assume Docker Hub by default, which produces a "not found" error for an image that genuinely exists, just not at the registry being implicitly assumed:

services:
  api:
    image: my-api:1.4.0

services:
  api:
    image: registry.example.com/my-api:1.4.0

This is a particularly easy mistake when copying a Compose file between environments or when an image was originally pushed to a private registry but the reference was written, perhaps out of habit, without the full registry hostname prefix.

Registry authentication required

A reference that is otherwise entirely correct can still fail to resolve if the registry hosting it requires authentication and Compose, or the underlying Docker daemon, has not been authenticated against it:

Error response from daemon: pull access denied for registry.example.com/my-api, repository does not exist or may require 'docker login'

docker login registry.example.com
docker compose up -d

This error message is somewhat ambiguous by design, since registries generally do not distinguish between "this image does not exist" and "you are not authorized to see it," both producing an identical error to avoid leaking information about private repository contents to unauthenticated requests; authenticating first and retrying clarifies which of the two situations actually applies.

Local versus remote image name collisions

A locally built image sharing the same name as a remote one can produce confusing behavior if Compose's pull policy results in an unexpected choice between the locally available image and a remote one with the identical reference:

services:
  api:
    image: my-api:latest
    build: .

docker compose up -d --build

docker compose up -d

The first command explicitly rebuilds and uses the freshly built local image; the second, without --build, may use whatever image already exists locally under that exact tag, without rebuilding, which can be surprising if a code change was expected to take effect but the existing, stale local image was used instead because nothing forced a rebuild or pull.

Pull policy configuration

Compose supports an explicit pull_policy setting controlling exactly when an image should be pulled versus reused from local cache, which resolves ambiguity about this behavior directly rather than relying on Compose's own default heuristics:

services:
  api:
    image: registry.example.com/my-api:latest
    pull_policy: always

Setting pull_policy: always for a service using a mutable tag like latest ensures the most current version is always fetched, rather than potentially reusing a stale, locally cached copy from an earlier pull, which is particularly relevant for any tag intended to represent "whatever is currently the latest published version" rather than a fixed, immutable reference.

Platform mismatch producing a resolution error

For a multi-architecture image reference, an explicit platform requirement that does not match any variant actually present in the image's manifest list produces a resolution failure distinct from the image simply not existing at all:

services:
  api:
    image: registry.example.com/my-api:1.4.0
    platform: linux/arm64

no matching manifest for linux/arm64 in the manifest list entries

This confirms the image reference itself is valid, but the specific platform variant requested was never actually built and published as part of that image's manifest list, which is a different, more specific problem than a missing or misspelled image reference entirely.

Verifying a reference resolves correctly outside of Compose

For any persistent image reference error, confirming the exact same reference resolves correctly with a direct docker pull, outside of Compose's own configuration merging and interpolation, isolates whether the problem is in the reference itself or in how Compose is constructing or interpreting it:

docker compose config | grep "image:"
docker pull <exact reference shown above>

Extracting the exact, fully resolved reference Compose is actually attempting to use, after any variable interpolation, and testing that precise string directly with docker pull removes any ambiguity about whether the issue lies in the reference itself or somewhere in Compose's own resolution and interpolation logic.

Common mistakes

• Assuming a manifest-not-found error means the registry is unreachable, when it actually means the registry was reached successfully but does not have an image matching the specific reference requested.
• Omitting the registry hostname prefix for an image hosted somewhere other than Docker Hub, causing Docker to incorrectly assume Docker Hub by default.
• Not authenticating to a private registry before attempting to pull from it, encountering an ambiguous error that could equally indicate a missing image or insufficient authorization.
• Relying on Compose's default pull behavior for a mutable tag without setting an explicit pull_policy, risking use of a stale, locally cached image rather than the current, intended version.
• Assuming a platform-specific resolution failure indicates the image reference itself is wrong, rather than recognizing it as a separate issue, the requested platform simply not being included in that image's manifest list.

Compose image reference errors are generally resolved efficiently by extracting the exact, fully interpolated reference Compose is attempting to use and testing it directly with docker pull, which isolates whether the problem is a genuine typo, a missing registry prefix, an authentication gap, or a platform mismatch, each of which has its own clear, specific fix once correctly identified.