{"record":{"id":"12c912ee12a668dc","repo":"docker/cli","slug":"images-options-are-incompatible-with-type-volume","errorCode":null,"errorMessage":"images options are incompatible with type volume","messagePattern":"images options are incompatible with type volume","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/volume.go","lineNumber":45,"sourceCode":"func createMountFromVolume(volume composetypes.ServiceVolumeConfig) mount.Mount {\n\treturn mount.Mount{\n\t\tType:        mount.Type(volume.Type),\n\t\tTarget:      volume.Target,\n\t\tReadOnly:    volume.ReadOnly,\n\t\tSource:      volume.Source,\n\t\tConsistency: mount.Consistency(volume.Consistency),\n\t}\n}\n\nfunc handleVolumeToMount(\n\tvolume composetypes.ServiceVolumeConfig,\n\tstackVolumes volumes,\n\tnamespace Namespace,\n) (mount.Mount, error) {\n\tresult := createMountFromVolume(volume)\n\n\tif volume.Image != nil {\n\t\treturn mount.Mount{}, errors.New(\"images options are incompatible with type volume\")\n\t}\n\tif volume.Tmpfs != nil {\n\t\treturn mount.Mount{}, errors.New(\"tmpfs options are incompatible with type volume\")\n\t}\n\tif volume.Bind != nil {\n\t\treturn mount.Mount{}, errors.New(\"bind options are incompatible with type volume\")\n\t}\n\tif volume.Cluster != nil {\n\t\treturn mount.Mount{}, errors.New(\"cluster options are incompatible with type volume\")\n\t}\n\t// Anonymous volumes\n\tif volume.Source == \"\" {\n\t\treturn result, nil\n\t}\n\n\tstackVolume, exists := stackVolumes[volume.Source]\n\tif !exists {\n\t\treturn mount.Mount{}, fmt.Errorf(\"undefined volume %q\", volume.Source)","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/volume.go#L27-L63","documentation":"Returned by handleVolumeToMount (compose/convert/volume.go:44-45) when a Compose service volume is type: volume but also carries an 'image' sub-options block. Volume mounts and image mounts are distinct mount types with incompatible option sets; specifying image options on a volume mount is a configuration error caught during conversion (convertVolumeToMount dispatches by type at volume.go:243-245).","triggerScenarios":"In docker-compose.yml: a volumes entry like { type: volume, source: data, target: /data, image: { subpath: /x } }. The presence of volume.Image (non-nil) at line 44 triggers the error.","commonSituations":"Editing a long-form volume entry and leaving an 'image:' block after changing type to volume. YAML anchors/merge keys pulling in image options from another volume. Copy-paste from an image-mount example.","solutions":["Remove the 'image:' sub-key from the volume-type mount.","If you intended an image mount, set type: image and provide source (the image ref).","Validate the file with 'docker compose config'."],"exampleFix":"# before\nvolumes:\n  - type: volume\n    source: data\n    target: /data\n    image:\n      subpath: /app\n\n# after\nvolumes:\n  - type: volume\n    source: data\n    target: /data","handlingStrategy":"validation","validationCode":"// Ensure a volume-type mount does not carry foreign (image) options.\nfunc validateVolumeMount(v composetypes.ServiceVolumeConfig) error {\n    if (v.Type == \"volume\" || v.Type == \"\") && v.Image != nil {\n        return errors.New(\"image options are incompatible with type volume\")\n    }\n    return nil\n}","typeGuard":"// volumeMountHasNoForeignOptions reports whether a volume-type mount omits image/tmpfs/bind/cluster.\nfunc volumeMountHasNoForeignOptions(v composetypes.ServiceVolumeConfig) bool {\n    if v.Type != \"volume\" && v.Type != \"\" {\n        return true\n    }\n    return v.Image == nil && v.Tmpfs == nil && v.Bind == nil && v.Cluster == nil\n}","tryCatchPattern":null,"preventionTips":["Keep each volume entry's option block aligned with its type.","Avoid YAML anchors that merge an option block across mounts of different types.","Validate compose files with 'docker compose config' in CI."],"tags":["docker-compose","volumes","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"}