What causes "failed to resolve digest for %s: %w" in docker/compose?

Verify the reference exists and is pullable: docker pull (or docker manifest inspect ).

failed to resolve digest for %s: %w

Error message

failed to resolve digest for %s: %w

What it means

ImageDigestResolver resolves a manifest digest for an image reference by calling DistributionInspect against the registry (with encoded auth from the config file). Any registry-side failure — auth, unknown repository, network, unsupported API — is wrapped with the image name into this error. It is used to pin image references, e.g. when preparing a published artifact.

Source

Thrown at pkg/compose/pull.go:360

// It deliberately returns the registry descriptor digest — the multi-platform
// index digest for multi-arch images — via DistributionInspect: a published
// compose file must stay deployable on any platform. This is NOT the same
// digest kind as localContentDigest, which selects the platform-specific
// runnable manifest to compare a running container with a fresh build/pull;
// never funnel this resolution through the local content-digest producer, and
// never pin a published reference with a per-platform digest.
func ImageDigestResolver(ctx context.Context, file *configfile.ConfigFile, apiClient client.APIClient) func(named reference.Named) (digest.Digest, error) {
	return func(named reference.Named) (digest.Digest, error) {
		auth, err := encodedAuth(named, file)
		if err != nil {
			return "", err
		}
		inspect, err := apiClient.DistributionInspect(ctx, named.String(), client.DistributionInspectOptions{
			EncodedRegistryAuth: auth,
		})
		if err != nil {
			return "",
				fmt.Errorf("failed to resolve digest for %s: %w", named.String(), err)
		}
		return inspect.Descriptor.Digest, nil
	}
}

type authProvider interface {
	GetAuthConfig(registryHostname string) (clitypes.AuthConfig, error)
}

func encodedAuth(ref reference.Named, configFile authProvider) (string, error) {
	authConfig, err := configFile.GetAuthConfig(registry.GetAuthConfigKey(reference.Domain(ref)))
	if err != nil {
		return "", err
	}

	buf, err := json.Marshal(authConfig)
	if err != nil {
		return "", err

View on GitHub (pinned to ddc4b044b6)

Solutions

Verify the reference exists and is pullable: docker pull <image> (or docker manifest inspect <image>).
Re-authenticate: docker login <registry> with credentials that have read access to the repository.
Fix typos in the image name/tag and confirm the image was actually pushed.
Check registry reachability (DNS, TLS, proxy) and retry once network issues clear.

Example fix

# before
services:
  api:
    image: registry.example.com/team/api:v1.0   # tag never pushed

# after
services:
  api:
    image: registry.example.com/team/api:latest  # existing tag; or push v1.0 first

Defensive patterns

Strategy: retry

Validate before calling

func imageResolvable(ctx context.Context, cli client.APIClient, ref string) bool {
	_, err := cli.DistributionInspect(ctx, ref, client.DistributionInspectOptions{})
	return err == nil
}

Try / catch

dgst, err := resolver(named)
if err != nil {
    if strings.Contains(err.Error(), "failed to resolve digest") {
        if isAuthError(err) { /* re-login, retry once */ }
        if isNotFound(err) { /* push image first or fix tag */ }
    }
    return err
}

Prevention

Push images before referencing them in digest-pinning flows.
docker login to each registry before publish/pull operations.
Verify tags with docker manifest inspect in CI before compose runs.

When it happens

Trigger: Calling an API that pins digests (publish/commit-style flows) for an image that does not exist in the registry, the user lacks pull rights, credentials in the config file are stale, the registry is unreachable, or the reference includes a tag that was never pushed.

Common situations: Image not pushed yet before referencing it; docker login token expired; private registry with self-signed cert or network policy blocking it; typo in the image tag; referencing a local-only build output by digest-pinning path.

Related errors

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