{"record":{"id":"b56db9a39d60a834","repo":"docker/cli","slug":"volume-options-are-incompatible-with-type-image","errorCode":null,"errorMessage":"volume options are incompatible with type image","messagePattern":"volume options are incompatible with type image","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/volume.go","lineNumber":101,"sourceCode":"\tresult.VolumeOptions.Labels = addStackLabel(namespace, stackVolume.Labels)\n\tif stackVolume.Driver != \"\" || stackVolume.DriverOpts != nil {\n\t\tresult.VolumeOptions.DriverConfig = &mount.Driver{\n\t\t\tName:    stackVolume.Driver,\n\t\t\tOptions: stackVolume.DriverOpts,\n\t\t}\n\t}\n\n\treturn result, nil\n}\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","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/volume.go#L83-L119","documentation":"Returned by handleImageToMount (volume.go:100-101) when a Compose service volume is type: image but also carries a 'volume' sub-options block (nocopy/subpath). Volume options only apply to type: volume mounts; combining them with an image mount is rejected during conversion.","triggerScenarios":"In docker-compose.yml: { type: image, source: myimg:latest, target: /app, volume: { nocopy: true } }. volume.Volume non-nil at line 100 triggers the error.","commonSituations":"Changing a mount from volume to image type but leaving the volume options. YAML anchors merging a volume block into an image entry. Template defaults that emit volume: {} for all mounts.","solutions":["Remove the 'volume:' sub-key from the image-type mount.","If you need nocopy/subpath volume semantics, use type: volume instead.","For an image mount, only 'image.subpath' is valid - express it under 'image:'."],"exampleFix":"# before\nvolumes:\n  - type: image\n    source: myimg:latest\n    target: /app\n    volume:\n      nocopy: true\n\n# after\nvolumes:\n  - type: image\n    source: myimg:latest\n    target: /app\n    image:\n      subpath: /app","handlingStrategy":"validation","validationCode":"// Ensure an image-type mount does not carry volume options.\nfunc validateImageMount(v composetypes.ServiceVolumeConfig) error {\n    if v.Type == \"image\" && v.Volume != nil {\n        return errors.New(\"volume options are incompatible with type image\")\n    }\n    return nil\n}","typeGuard":"// imageMountHasNoForeignOptions reports whether an image-type mount omits volume/bind/tmpfs/cluster.\nfunc imageMountHasNoForeignOptions(v composetypes.ServiceVolumeConfig) bool {\n    if v.Type != \"image\" {\n        return true\n    }\n    return v.Volume == nil && v.Bind == nil && v.Tmpfs == nil && v.Cluster == nil\n}","tryCatchPattern":null,"preventionTips":["For image mounts, only the 'image.subpath' option is valid - put it under 'image:'.","Remove 'volume:' options when switching a mount to type: image.","Avoid YAML anchors that merge volume options into image entries."],"tags":["docker-compose","volumes","image-mount","mount","type-conflict","validation","convert"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}