cluster options are incompatible with type volume

Error message

cluster options are incompatible with type volume

What it means

Raised by handleVolumeToMount when a mount of type 'volume' (or defaulted empty type) also specifies a 'cluster:' options block. Cluster options belong exclusively to Swarm CSI cluster volumes (type: cluster); the converter rejects the mix so the engine never receives contradictory mount option structs.

Source

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

func handleVolumeToMount(
	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,
	namespace Namespace,
) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Image != nil {
		return mount.Mount{}, errors.New("images options are incompatible with type volume")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type volume")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type volume")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type volume")
	}
	// Anonymous volumes
	if volume.Source == "" {
		return result, nil
	}

	stackVolume, exists := stackVolumes[volume.Source]
	if !exists {
		return mount.Mount{}, fmt.Errorf("undefined volume %q", volume.Source)
	}

	result.Source = namespace.Scope(volume.Source)
	result.VolumeOptions = &mount.VolumeOptions{}

	if volume.Volume != nil {
		result.VolumeOptions.NoCopy = volume.Volume.NoCopy
		result.VolumeOptions.Subpath = volume.Volume.Subpath
	}

View on GitHub (pinned to e9452d6e78)

Solutions

Change 'type: volume' to 'type: cluster' if you intend a Swarm CSI cluster volume, or delete the 'cluster:' block.
Verify with 'docker compose config' that each mount entry carries only options matching its type.

Example fix

# before
volumes:
  - type: volume
    source: shared
    target: /data
    cluster: {}
# after
volumes:
  - type: cluster
    source: shared
    target: /data

When it happens

Trigger: 'docker stack deploy' with a compose service volume entry having type: volume (or no type) plus a cluster: sub-mapping.

Common situations: Migrating a named volume to a Swarm CSI cluster volume and adding cluster options without changing the type; YAML merge keys spreading cluster options across entries.

Related errors

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/702002ad3e45dc3a.json. Report an issue: GitHub.