volume options are incompatible with type image

Error message

volume options are incompatible with type image

What it means

Raised by handleImageToMount when a mount of type 'image' also carries a 'volume:' options block (nocopy, subpath for named volumes). Image mounts accept only image options, so the converter rejects the entry rather than silently dropping the volume options.

Source

Thrown at cli/compose/convert/volume.go:101

	result.VolumeOptions.Labels = addStackLabel(namespace, stackVolume.Labels)
	if stackVolume.Driver != "" || stackVolume.DriverOpts != nil {
		result.VolumeOptions.DriverConfig = &mount.Driver{
			Name:    stackVolume.Driver,
			Options: stackVolume.DriverOpts,
		}
	}

	return result, nil
}

func handleImageToMount(volume composetypes.ServiceVolumeConfig) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Source == "" {
		return mount.Mount{}, errors.New("invalid image source, source cannot be empty")
	}
	if volume.Volume != nil {
		return mount.Mount{}, errors.New("volume options are incompatible with type image")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type image")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type image")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type image")
	}
	if volume.Image != nil {
		result.ImageOptions = &mount.ImageOptions{
			Subpath: volume.Image.Subpath,
		}
	}
	return result, nil
}

View on GitHub (pinned to e9452d6e78)

Solutions

Delete the 'volume:' block; if you needed subpath, move it under 'image:' (image: {subpath: some/dir}).
If a named volume was intended, change type back to volume.

Example fix

# before
volumes:
  - type: image
    source: alpine:latest
    target: /mnt/img
    volume:
      subpath: etc
# after
volumes:
  - type: image
    source: alpine:latest
    target: /mnt/img
    image:
      subpath: etc

When it happens

Trigger: 'docker stack deploy' with a service volume entry combining type: image and a volume: sub-mapping such as volume: {nocopy: true}.

Common situations: Converting a named-volume entry to an image mount and leaving the volume: block behind; note volume.subpath has an image-mount equivalent under image: subpath, which is the usual intended fix.

Related errors

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/b56db9a39d60a834.json. Report an issue: GitHub.