docker/cli · error

images options are incompatible with type volume

Error message

images options are incompatible with type volume

What it means

Raised by handleVolumeToMount in the compose-to-swarm volume converter when a service mount of `type: volume` carries an `image:` options block. The image sub-options only apply to image-type mounts, so pairing them with a volume mount is a config contradiction the converter rejects up front (the same guard exists for tmpfs, bind, and cluster options).

Source

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

func createMountFromVolume(volume composetypes.ServiceVolumeConfig) mount.Mount {
	return mount.Mount{
		Type:        mount.Type(volume.Type),
		Target:      volume.Target,
		ReadOnly:    volume.ReadOnly,
		Source:      volume.Source,
		Consistency: mount.Consistency(volume.Consistency),
	}
}

func handleVolumeToMount(
	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,
	namespace Namespace,
) (mount.Mount, error) {
	result := createMountFromVolume(volume)

	if volume.Image != nil {
		return mount.Mount{}, errors.New("images options are incompatible with type volume")
	}
	if volume.Tmpfs != nil {
		return mount.Mount{}, errors.New("tmpfs options are incompatible with type volume")
	}
	if volume.Bind != nil {
		return mount.Mount{}, errors.New("bind options are incompatible with type volume")
	}
	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type volume")
	}
	// Anonymous volumes
	if volume.Source == "" {
		return result, nil
	}

	stackVolume, exists := stackVolumes[volume.Source]
	if !exists {
		return mount.Mount{}, fmt.Errorf("undefined volume %q", volume.Source)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Remove the `image:` block from the mount, or change the mount to `type: image` if an image mount is what you want
2. Check YAML indentation so image options aren't accidentally attached to a volume mount
3. Validate the file with `docker compose config` before deploying

Example fix

# before
volumes:
  - type: volume
    source: data
    target: /data
    image:
      subpath: app
# after
volumes:
  - type: volume
    source: data
    target: /data

When it happens

Trigger: `docker stack deploy` where a service volume entry uses long syntax with `type: volume` plus an `image:` key, e.g. `- {type: volume, source: data, target: /data, image: {subpath: ...}}`. Any non-nil Image struct on a volume-type mount triggers it.

Common situations: Copying an image-mount example and changing type to volume without removing the image block; YAML indentation mistakes nesting image options under the wrong mount; experimenting with the newer image-mount feature and mixing it into an existing volume definition.

Related errors

• tmpfs options are incompatible with type volume
• invalid restart policy: maximum retry count cannot be negati
• duplicate mount target
• conflicting options: cannot specify a volume-name through bo
• can only update cluster volumes

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