docker/cli · error

cluster options are incompatible with type volume

Error message

cluster options are incompatible with type volume

What it means

Returned by handleVolumeToMount (volume.go:53-54) when a Compose service volume is type: volume but also carries a 'cluster' sub-options block. Cluster options only apply to type: cluster (Swarm cluster volume) mounts; mixing them into a normal volume mount is rejected during conversion.

Solutions

1. Remove the 'cluster:' sub-key from the volume-type mount.
2. If cluster-volume semantics are intended, set type: cluster and ensure the source is a defined cluster volume.
3. Run 'docker compose config' to verify.

Example fix

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

# after
volumes:
  - type: cluster
    source: cdata
    target: /data

// Ensure a volume-type mount does not carry cluster options.
func validateVolumeMount(v composetypes.ServiceVolumeConfig) error {
    if (v.Type == "volume" || v.Type == "") && v.Cluster != nil {
        return errors.New("cluster options are incompatible with type volume")
    }
    return nil
}

// volumeMountHasNoForeignOptions reports whether a volume-type mount omits image/tmpfs/bind/cluster.
func volumeMountHasNoForeignOptions(v composetypes.ServiceVolumeConfig) bool {
    if v.Type != "volume" && v.Type != "" {
        return true
    }
    return v.Image == nil && v.Tmpfs == nil && v.Bind == nil && v.Cluster == nil
}

When it happens

Trigger: In docker-compose.yml: { type: volume, source: data, target: /data, cluster: { } }. volume.Cluster non-nil at line 53 triggers the error.

Common situations: Promoting a local volume entry to use cluster options but forgetting to change type to 'cluster'. YAML merge keys importing a cluster block. Template defaults that emit cluster: {} for all mounts.

Related errors

• images options are incompatible with type volume
• tmpfs options are incompatible with type volume
• bind options are incompatible with type volume
• volume options are incompatible with type image
• bind options are incompatible with type image

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

Appendix: 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 4f84911bfe)