cluster options are incompatible with type image

Error message

cluster options are incompatible with type image

What it means

Returned by handleImageToMount (cli/compose/convert/volume.go:109-110) when a service volume has type "image" but also carries a non-nil Cluster options block. An image mount is backed by a layer inside an image and only accepts image-specific options (image.subpath); cluster options are semantically meaningless for it, so the converter rejects the combination instead of silently discarding it. ClusterOpts is an empty struct, so even an empty `cluster: {}` or `cluster:` key sets the pointer and trips this guard.

Solutions

Remove the `cluster:` key from the volume entry that uses `type: image`.
If you actually want a cluster volume, change `type:` to `cluster` and drop the `image:` block.
Search the compose file for YAML anchors/merge keys (`<<: *something`) that may be injecting the `cluster:` field.

Example fix

# before
volumes:
  - type: image
    source: myimg
    target: /data
    cluster: {}

# after
volumes:
  - type: image
    source: myimg
    target: /data

Defensive patterns

Strategy: validation

Validate before calling

// Run before convert.Volumes(...)
for i, v := range serviceVolumes {
    if v.Type == "image" && v.Cluster != nil {
        return fmt.Errorf("service volume[%d] target=%q: type image must not declare a cluster block", i, v.Target)
    }
}

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil {
    if strings.Contains(err.Error(), "cluster options are incompatible with type image") {
        // surface to the user as a compose-file config error, not a runtime fault
        return fmt.Errorf("compose config error: %w (remove the cluster: block from the image volume)", err)
    }
    return err
}

Prevention

Keep one options block per volume entry; never mix `cluster:` with another type.
Lint compose files with `docker compose config` before deploy so incompatible blocks fail fast.
Avoid YAML anchors that inject option blocks across volume entries of different types.

When it happens

Trigger: Passing a composetypes.ServiceVolumeConfig with Type=="image" and Cluster!=nil to convert.Volumes() / convertVolumeToMount(). In YAML this is a volume entry containing both `type: image` and a `cluster:` (even empty) key.

Common situations: Copy-pasting a cluster-volume example into an image-volume block; YAML merge keys/anchors that inject an unwanted `cluster:` field; refactoring a volume from cluster to image and forgetting to strip the old options.

Related errors

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

Appendix: source

Thrown at cli/compose/convert/volume.go:110

}

func handleImageToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid image source, source cannot be empty")
	}
	if volume.Volume != nil {
		return mount.Mount{}, errors.New("volume options are incompatible with type image")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type image")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type image")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type image")
	}
	if volume.Image != nil {
		result.ImageOptions = &mount.ImageOptions{
			Subpath: volume.Image.Subpath,
		}
	}
	return result, nil
}

func handleBindToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid bind source, source cannot be empty")
	}
	if volume.Volume != nil {
		return mount.Mount{}, errors.New("volume options are incompatible with type bind")
	}

View on GitHub (pinned to 4f84911bfe)