docker/cli · error

error mounting to

Error message

error mounting %s to %s

What it means

Returned by `mountBlobs` (push.go:278-285) when a cross-repo blob mount returns `registryclient.ErrBlobCreated` for a blob whose platform OS is NOT windows. ErrBlobCreated means the blob wasn't already present and had to be created/mounted; for non-windows blobs this is treated as a push failure because the blob should have been pre-pushed to the target repo. Windows is excepted because foreign-layer cross-mounting is expected.

Solutions

1. Pre-push the source images (or their layers) to the target repository first.
2. Re-run the push after the layers exist in the target repo.
3. Confirm the target registry supports cross-repo blob mounting.
4. If genuinely a Windows target, ensure the platform OS is set to windows so the exception applies.

Example fix

# before
docker manifest create reg.io/mylist reg.io/source:tag
docker manifest push reg.io/mylist   # non-windows layer mount failed
# after
docker push reg.io/source:tag        # ensure layers exist in repo
docker manifest push reg.io/mylist

// ensure target repo already has the layers before manifest-list push
for _, blob := range requiredBlobs {
    exists, err := registryClient.BlobExists(ctx, targetRepo, blob.digest)
    if err != nil || !exists {
        return fmt.Errorf("layer %s not in target repo; push the source image first", blob.digest)
    }
}

if err := runPush(ctx, cli, opts); err != nil {
    if strings.Contains(err.Error(), "error mounting") {
        // pre-push source layers, then retry
        return pushSourceLayersThenRetry(manifests, targetRef)
    }
    return err
}

When it happens

Trigger: Pushing a manifest list that references cross-repo source images where the underlying layers are not yet present in the target repository on a non-windows platform, and the registry creates the blob mount rather than finding it.

Common situations: Cross-repo manifest-list push where the source images' layers were never pushed to the target repo, or an registry that doesn't support blob-by-mount and reports ErrBlobCreated.

Related errors

• manifest must have an OS and Architecture to be pushed to a…
• cannot use source images from a different registry than the…
• failed to assemble ManifestDescriptor
• not found
• digest parse of image

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/5360048beaf65446. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/manifest/push.go:284

func pushReferences(ctx context.Context, out io.Writer, client registryclient.RegistryClient, mounts []mountRequest) error {
	for _, mount := range mounts {
		newDigest, err := client.PutManifest(ctx, mount.ref, mount.manifest)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(out, "Pushed ref %s with digest: %s\n", mount.ref, newDigest)
	}
	return nil
}

func mountBlobs(ctx context.Context, client registryclient.RegistryClient, ref reference.Named, blobs []manifestBlob) error {
	for _, blob := range blobs {
		err := client.MountBlob(ctx, blob.canonical, ref)
		switch err.(type) {
		case nil:
		case registryclient.ErrBlobCreated:
			if blob.os != "windows" {
				return fmt.Errorf("error mounting %s to %s", blob.canonical, ref)
			}
		default:
			return err
		}
	}
	return nil
}

View on GitHub (pinned to 4f84911bfe)