volume options are incompatible with type image

Error message

volume options are incompatible with type image

What it means

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.

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

Example fix

# before
volumes:
  - type: image
    source: myimg:latest
    target: /app
    volume:
      nocopy: true

# after
volumes:
  - type: image
    source: myimg:latest
    target: /app
    image:
      subpath: /app

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

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.

When it happens

Trigger: In docker-compose.yml: { type: image, source: myimg:latest, target: /app, volume: { nocopy: true } }. volume.Volume non-nil at line 100 triggers the error.

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

Related errors

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

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