invalid cluster source, source cannot be empty

Error message

invalid cluster source, source cannot be empty

What it means

Returned by handleClusterToMount (cli/compose/convert/volume.go:200-201). A Swarm cluster volume is identified by its source (a volume name or a `group:<name>` reference), so an empty source leaves the mount unresolved. The handler refuses to proceed and never reaches the stack-volume lookup at cli/compose/convert/volume.go:221.

Solutions

Add a non-empty `source:` naming the cluster volume or a group (`source: group:mygroup`).
Guard interpolation: `source: ${CVOL_NAME:?must be set}`.
If the source is not a `group:` reference, ensure it is declared under the top-level `volumes:` map or marked external.

Example fix

# before
volumes:
  - type: cluster
    target: /data

# 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" && strings.TrimSpace(v.Source) == "" {
        return fmt.Errorf("service volume[%d] target=%q: cluster volume requires a non-empty source (volume name or group:<name>)", i, v.Target)
    }
}

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil && strings.Contains(err.Error(), "invalid cluster source") {
    return fmt.Errorf("compose config error: %w (set source: to a cluster volume name or group:<name>)", err)
}

Prevention

Always provide a `source:` for cluster volumes; `group:<name>` skips the stack-volume lookup.
Use `${VAR:?must be set}` for interpolated volume names.
Define the source under top-level `volumes:` or mark it external.

When it happens

Trigger: ServiceVolumeConfig with Type=="cluster" and Source=="" passed to convertVolumeToMount().

Common situations: `type: cluster` with no `source:`; interpolation of a volume name that resolved to empty; forgetting to define the source when converting from a named volume.

Related errors

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

Appendix: source

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

	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type npipe")
	}
	if volume.Bind != nil {
		result.BindOptions = &mount.BindOptions{
			Propagation: mount.Propagation(volume.Bind.Propagation),
		}
	}
	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

View on GitHub (pinned to 4f84911bfe)