docker/compose · error

unable to get image '%s': %w

Error message

unable to get image '%s': %w

What it means

While building the per-repoTag image inspection map (used for image status/labeling), compose calls ImageInspect concurrently for each tag. NotFound is tolerated (tag simply absent), but any other engine error is wrapped with the offending repoTag. So this always indicates a real Docker API failure, not a missing image.

Source

Thrown at pkg/compose/images.go:175

// inspectLocalImages inspects the given references in parallel, requesting
// per-manifest data on engines that support it. References not found locally
// are simply absent from the result.
func (s *composeService) inspectLocalImages(ctx context.Context, repoTags []string) (map[string]client.ImageInspectResult, error) {
	opts, err := s.imageInspectOptions(ctx)
	if err != nil {
		return nil, err
	}
	inspections := map[string]client.ImageInspectResult{}
	l := sync.Mutex{}
	eg, ctx := errgroup.WithContext(ctx)
	for _, repoTag := range repoTags {
		eg.Go(func() error {
			inspect, err := s.apiClient().ImageInspect(ctx, repoTag, opts...)
			if err != nil {
				if errdefs.IsNotFound(err) {
					return nil
				}
				return fmt.Errorf("unable to get image '%s': %w", repoTag, err)
			}
			l.Lock()
			inspections[repoTag] = inspect
			l.Unlock()
			return nil
		})
	}
	return inspections, eg.Wait()
}

// imageInspectOptions requests per-manifest data when the engine supports it
// (see manifestsSupported).
func (s *composeService) imageInspectOptions(ctx context.Context) ([]client.ImageInspectOption, error) {
	withManifests, err := s.manifestsSupported(ctx)
	if err != nil {
		return nil, err
	}
	if !withManifests {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Verify manually: docker image inspect '<repoTag>' and check the engine error
2. Check daemon health (docker info) and retry the compose command if the daemon was restarting
3. Fix the image reference (typo in tag/digest) in the compose file
4. For private registries, docker login again so the daemon can resolve the reference

// cheap pre-flight: daemon reachable and image inspect doesn't hard-error
if _, err := cli.ImageInspect(ctx, ref); err != nil && !errdefs.IsNotFound(err) {
    return err // surface engine problem before running compose
}

var err error
for attempt := 0; attempt < 3; attempt++ {
    _, err = composeService.Images(ctx, project, false)
    if err == nil || !strings.Contains(err.Error(), "unable to get image") {
        break
    }
    time.Sleep(backoff(attempt))
}

When it happens

Trigger: ImageInspect returning a non-404 error for one of the service's repoTags: daemon unreachable mid-request, registry auth required for a digest resolution, malformed reference, or engine internal error.

Common situations: Docker daemon restarting or under load during compose up/ps; DOCKER_HOST pointing at a remote daemon with flaky connectivity; image reference with an invalid digest or tag format; rate-limited registry auth.

Related errors

• your Compose stack cannot be published as it only contains a
• unsupported OCI version: %s
• creating fetcher for %s: %w
• fetching blob %s: %w
• reading blob %s: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/717294eebfc19ee9. Report an issue: GitHub.