docker/cli · error

volume options are incompatible with type cluster

Error message

volume options are incompatible with type cluster

What it means

Error "volume options are incompatible with type cluster" thrown in docker/cli.

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 e9452d6e78)

When it happens

Trigger: Thrown at cli/compose/convert/volume.go:210 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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