bind options are incompatible with type volume

Error message

bind options are incompatible with type volume

What it means

Returned by handleVolumeToMount (volume.go:50-51) when a Compose service volume is type: volume but also carries a 'bind' sub-options block (e.g. propagation). Bind options only apply to type: bind mounts; combining them with a volume mount is rejected during conversion.

Solutions

Remove the 'bind:' sub-key from the volume-type mount.
If you need bind propagation semantics, set type: bind and supply a host path as source.
Validate with 'docker compose config'.

Example fix

# before
volumes:
  - type: volume
    source: data
    target: /data
    bind:
      propagation: rshared

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

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a volume-type mount does not carry bind options.
func validateVolumeMount(v composetypes.ServiceVolumeConfig) error {
    if (v.Type == "volume" || v.Type == "") && v.Bind != nil {
        return errors.New("bind 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

When switching from bind to volume, drop propagation/bind sub-options.
Avoid option-block YAML anchors shared between bind and volume mounts.
Validate with 'docker compose config'.

When it happens

Trigger: In docker-compose.yml: { type: volume, source: data, target: /data, bind: { propagation: rshared } }. volume.Bind non-nil at line 50 triggers the error.

Common situations: Switching a mount from bind to volume (e.g. to use a named volume) but leaving the propagation/bind options. YAML merge keys importing a bind block. Copy-paste from a bind example.

Related errors

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

Appendix: source

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

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

	result.Source = namespace.Scope(volume.Source)
	result.VolumeOptions = &mount.VolumeOptions{}

	if volume.Volume != nil {

View on GitHub (pinned to 4f84911bfe)