{"record":{"id":"c20c214802040c2f","repo":"docker/cli","slug":"cluster-options-are-incompatible-with-type-image","errorCode":null,"errorMessage":"cluster options are incompatible with type image","messagePattern":"cluster options are incompatible with type image","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/volume.go","lineNumber":110,"sourceCode":"}\n\nfunc handleImageToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {\n\tresult := createMountFromVolume(volume)\n\n\tif volume.Source == \"\" {\n\t\treturn mount.Mount{}, errors.New(\"invalid image source, source cannot be empty\")\n\t}\n\tif volume.Volume != nil {\n\t\treturn mount.Mount{}, errors.New(\"volume options are incompatible with type image\")\n\t}\n\tif volume.Bind != nil {\n\t\treturn mount.Mount{}, errors.New(\"bind options are incompatible with type image\")\n\t}\n\tif volume.Tmpfs != nil {\n\t\treturn mount.Mount{}, errors.New(\"tmpfs options are incompatible with type image\")\n\t}\n\tif volume.Cluster != nil {\n\t\treturn mount.Mount{}, errors.New(\"cluster options are incompatible with type image\")\n\t}\n\tif volume.Image != nil {\n\t\tresult.ImageOptions = &mount.ImageOptions{\n\t\t\tSubpath: volume.Image.Subpath,\n\t\t}\n\t}\n\treturn result, nil\n}\n\nfunc handleBindToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {\n\tresult := createMountFromVolume(volume)\n\n\tif volume.Source == \"\" {\n\t\treturn mount.Mount{}, errors.New(\"invalid bind source, source cannot be empty\")\n\t}\n\tif volume.Volume != nil {\n\t\treturn mount.Mount{}, errors.New(\"volume options are incompatible with type bind\")\n\t}","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/volume.go#L92-L128","documentation":"Returned by handleImageToMount (cli/compose/convert/volume.go:109-110) when a service volume has type \"image\" but also carries a non-nil Cluster options block. An image mount is backed by a layer inside an image and only accepts image-specific options (image.subpath); cluster options are semantically meaningless for it, so the converter rejects the combination instead of silently discarding it. ClusterOpts is an empty struct, so even an empty `cluster: {}` or `cluster:` key sets the pointer and trips this guard.","triggerScenarios":"Passing a composetypes.ServiceVolumeConfig with Type==\"image\" and Cluster!=nil to convert.Volumes() / convertVolumeToMount(). In YAML this is a volume entry containing both `type: image` and a `cluster:` (even empty) key.","commonSituations":"Copy-pasting a cluster-volume example into an image-volume block; YAML merge keys/anchors that inject an unwanted `cluster:` field; refactoring a volume from cluster to image and forgetting to strip the old options.","solutions":["Remove the `cluster:` key from the volume entry that uses `type: image`.","If you actually want a cluster volume, change `type:` to `cluster` and drop the `image:` block.","Search the compose file for YAML anchors/merge keys (`<<: *something`) that may be injecting the `cluster:` field."],"exampleFix":"# before\nvolumes:\n  - type: image\n    source: myimg\n    target: /data\n    cluster: {}\n\n# after\nvolumes:\n  - type: image\n    source: myimg\n    target: /data","handlingStrategy":"validation","validationCode":"// Run before convert.Volumes(...)\nfor i, v := range serviceVolumes {\n    if v.Type == \"image\" && v.Cluster != nil {\n        return fmt.Errorf(\"service volume[%d] target=%q: type image must not declare a cluster block\", i, v.Target)\n    }\n}","typeGuard":null,"tryCatchPattern":"mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)\nif err != nil {\n    if strings.Contains(err.Error(), \"cluster options are incompatible with type image\") {\n        // surface to the user as a compose-file config error, not a runtime fault\n        return fmt.Errorf(\"compose config error: %w (remove the cluster: block from the image volume)\", err)\n    }\n    return err\n}","preventionTips":["Keep one options block per volume entry; never mix `cluster:` with another type.","Lint compose files with `docker compose config` before deploy so incompatible blocks fail fast.","Avoid YAML anchors that inject option blocks across volume entries of different types."],"tags":["docker","compose","volumes","image-mount","cluster-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"}