volume options are incompatible with type cluster

Error message

volume options are incompatible with type cluster

What it means

Returned by handleClusterToMount (cli/compose/convert/volume.go:209-210). nocopy/subpath are named-volume options; a cluster volume is a distinct Swarm resource and does not accept them, so a `volume:` block on a cluster entry is rejected. (Note the ordering: the handler checks tmpfs, then bind, then volume — image options are not checked for cluster.)

Solutions

Delete the `volume:` options block from the cluster entry.
If nocopy/subpath was required, restore `type: volume` and reference a named source.

Example fix

# before
volumes:
  - type: cluster
    source: my-cluster-vol
    target: /data
    volume:
      nocopy: true
      subpath: /sub

# after
volumes:
  - type: cluster
    source: my-cluster-vol
    target: /data

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil && strings.Contains(err.Error(), "volume options are incompatible with type cluster") {
    return fmt.Errorf("compose config error: %w (remove the volume: block from the cluster entry)", err)
}

Prevention

Cluster volumes are a distinct Swarm resource; do not reuse named-volume option blocks on them.
Lint compose files in CI to catch cross-type option conflicts.

When it happens

Trigger: ServiceVolumeConfig with Type=="cluster" and Volume!=nil passed to convertVolumeToMount().

Common situations: Reusing a named-volume entry and flipping type to cluster without removing the `volume:` block; copy-paste between definitions.

Related errors

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

Appendix: source

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

	return result, nil
}

func handleClusterToMount(
	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,
	namespace Namespace,
) (mount.Mount, error) {
	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid cluster source, source cannot be empty")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type cluster")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type cluster")
	}
	if volume.Volume != nil {
		return mount.Mount{}, errors.New("volume options are incompatible with type cluster")
	}

	result := createMountFromVolume(volume)
	result.ClusterOptions = &mount.ClusterOptions{}

	if !strings.HasPrefix(volume.Source, "group:") {
		// if the volume is a cluster volume and the source is a volumegroup, we
		// will ignore checking to see if such a volume is defined. the volume
		// group isn't namespaced, and there's no simple way to indicate that
		// external volumes with a given group exist.
		stackVolume, exists := stackVolumes[volume.Source]
		if !exists {
			return mount.Mount{}, fmt.Errorf("undefined volume %q", volume.Source)
		}

		// if the volume is not specified with a group source, we may namespace
		// the name, if one is not otherwise specified.
		if stackVolume.Name != "" {

View on GitHub (pinned to 4f84911bfe)