{"record":{"id":"de5c8cbadcc2d0ac","repo":"docker/cli","slug":"invalid-cluster-source-source-cannot-be-empty","errorCode":null,"errorMessage":"invalid cluster source, source cannot be empty","messagePattern":"invalid cluster source, source cannot be empty","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/volume.go","lineNumber":201,"sourceCode":"\t}\n\tif volume.Tmpfs != nil {\n\t\treturn mount.Mount{}, errors.New(\"tmpfs options are incompatible with type npipe\")\n\t}\n\tif volume.Bind != nil {\n\t\tresult.BindOptions = &mount.BindOptions{\n\t\t\tPropagation: mount.Propagation(volume.Bind.Propagation),\n\t\t}\n\t}\n\treturn result, nil\n}\n\nfunc handleClusterToMount(\n\tvolume composetypes.ServiceVolumeConfig,\n\tstackVolumes volumes,\n\tnamespace Namespace,\n) (mount.Mount, error) {\n\tif volume.Source == \"\" {\n\t\treturn mount.Mount{}, errors.New(\"invalid cluster source, source cannot be empty\")\n\t}\n\tif volume.Tmpfs != nil {\n\t\treturn mount.Mount{}, errors.New(\"tmpfs options are incompatible with type cluster\")\n\t}\n\tif volume.Bind != nil {\n\t\treturn mount.Mount{}, errors.New(\"bind options are incompatible with type cluster\")\n\t}\n\tif volume.Volume != nil {\n\t\treturn mount.Mount{}, errors.New(\"volume options are incompatible with type cluster\")\n\t}\n\n\tresult := createMountFromVolume(volume)\n\tresult.ClusterOptions = &mount.ClusterOptions{}\n\n\tif !strings.HasPrefix(volume.Source, \"group:\") {\n\t\t// if the volume is a cluster volume and the source is a volumegroup, we\n\t\t// will ignore checking to see if such a volume is defined. the volume\n\t\t// group isn't namespaced, and there's no simple way to indicate that","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/volume.go#L183-L219","documentation":"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.","triggerScenarios":"ServiceVolumeConfig with Type==\"cluster\" and Source==\"\" passed to convertVolumeToMount().","commonSituations":"`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.","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."],"exampleFix":"# before\nvolumes:\n  - type: cluster\n    target: /data\n\n# after\nvolumes:\n  - type: cluster\n    source: my-cluster-vol\n    target: /data","handlingStrategy":"validation","validationCode":"for i, v := range serviceVolumes {\n    if v.Type == \"cluster\" && strings.TrimSpace(v.Source) == \"\" {\n        return fmt.Errorf(\"service volume[%d] target=%q: cluster volume requires a non-empty source (volume name or group:<name>)\", i, v.Target)\n    }\n}","typeGuard":null,"tryCatchPattern":"mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)\nif err != nil && strings.Contains(err.Error(), \"invalid cluster source\") {\n    return fmt.Errorf(\"compose config error: %w (set source: to a cluster volume name or group:<name>)\", err)\n}","preventionTips":["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."],"tags":["docker","compose","volumes","cluster-volume","swarm","config-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}