{"record":{"id":"0d2f1009e80989b3","repo":"docker/cli","slug":"volume-options-are-incompatible-with-type-cluster","errorCode":null,"errorMessage":"volume options are incompatible with type cluster","messagePattern":"volume options are incompatible with type cluster","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/volume.go","lineNumber":210,"sourceCode":"\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\n\t\t// external volumes with a given group exist.\n\t\tstackVolume, exists := stackVolumes[volume.Source]\n\t\tif !exists {\n\t\t\treturn mount.Mount{}, fmt.Errorf(\"undefined volume %q\", volume.Source)\n\t\t}\n\n\t\t// if the volume is not specified with a group source, we may namespace\n\t\t// the name, if one is not otherwise specified.\n\t\tif stackVolume.Name != \"\" {","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/volume.go#L192-L228","documentation":"Returned by handleClusterToMount (cli/compose/convert/volume.go:209-210). nocopy/subpath are named-volume options; a cluster volume is a distinct Swarm resource and does not accept them, so a `volume:` block on a cluster entry is rejected. (Note the ordering: the handler checks tmpfs, then bind, then volume — image options are not checked for cluster.)","triggerScenarios":"ServiceVolumeConfig with Type==\"cluster\" and Volume!=nil passed to convertVolumeToMount().","commonSituations":"Reusing a named-volume entry and flipping type to cluster without removing the `volume:` block; copy-paste between definitions.","solutions":["Delete the `volume:` options block from the cluster entry.","If nocopy/subpath was required, restore `type: volume` and reference a named source."],"exampleFix":"# before\nvolumes:\n  - type: cluster\n    source: my-cluster-vol\n    target: /data\n    volume:\n      nocopy: true\n      subpath: /sub\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\" && v.Volume != nil {\n        return fmt.Errorf(\"service volume[%d] target=%q: type cluster must not declare a volume block\", i, v.Target)\n    }\n}","typeGuard":null,"tryCatchPattern":"mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)\nif err != nil && strings.Contains(err.Error(), \"volume options are incompatible with type cluster\") {\n    return fmt.Errorf(\"compose config error: %w (remove the volume: block from the cluster entry)\", err)\n}","preventionTips":["Cluster volumes are a distinct Swarm resource; do not reuse named-volume option blocks on them.","Lint compose files in CI to catch cross-type option conflicts."],"tags":["docker","compose","volumes","cluster-volume","named-volume","config-validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}