images options are incompatible with type volume

Error message

images options are incompatible with type volume

What it means

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).

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'.

Example fix

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

# after
volumes:
  - type: volume
    source: data
    target: /data

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a volume-type mount does not carry foreign (image) options.
func validateVolumeMount(v composetypes.ServiceVolumeConfig) error {
    if (v.Type == "volume" || v.Type == "") && v.Image != nil {
        return errors.New("image options are incompatible with type volume")
    }
    return nil
}

Type guard

// volumeMountHasNoForeignOptions reports whether a volume-type mount omits image/tmpfs/bind/cluster.
func volumeMountHasNoForeignOptions(v composetypes.ServiceVolumeConfig) bool {
    if v.Type != "volume" && v.Type != "" {
        return true
    }
    return v.Image == nil && v.Tmpfs == nil && v.Bind == nil && v.Cluster == nil
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/12c912ee12a668dc. Report an issue: GitHub.

Appendix: 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 4f84911bfe)