volume options are incompatible with type bind

Error message

volume options are incompatible with type bind

What it means

Returned by handleBindToMount (cli/compose/convert/volume.go:126-127). The bind type only honours bind-specific options (propagation); volume options such as nocopy/subpath belong to named volumes and are rejected for binds. Supplying both signals a confused config that the converter will not silently fix.

Solutions

Delete the `volume:` options block from the bind entry.
If nocopy/subpath was intended, switch the entry back to `type: volume` and provide a named source defined under the top-level `volumes:` map.
Move propagation settings into the `bind:` block (e.g. `bind: { propagation: rshared }`).

Example fix

# before
volumes:
  - type: bind
    source: /host/data
    target: /data
    volume:
      nocopy: true

# after
volumes:
  - type: bind
    source: /host/data
    target: /data
    bind:
      propagation: rshared

Defensive patterns

Strategy: validation

Validate before calling

for i, v := range serviceVolumes {
    if v.Type == "bind" && v.Volume != nil {
        return fmt.Errorf("service volume[%d] target=%q: type bind must not declare a volume block", i, v.Target)
    }
}

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil && strings.Contains(err.Error(), "volume options are incompatible with type bind") {
    return fmt.Errorf("compose config error: %w (remove the volume: block from the bind entry)", err)
}

Prevention

When changing a volume's `type:`, audit its option blocks in the same edit.
Prefer one canonical options block per type in shared anchors to avoid cross-type leakage.

When it happens

Trigger: ServiceVolumeConfig with Type=="bind" and Volume!=nil (the `volume:` options block) reaching convertVolumeToMount().

Common situations: Changing `type: volume` to `type: bind` but leaving the `volume: { nocopy: true }` block in place; copy-paste from a named-volume example.

Related errors

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

Appendix: source

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

	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
}

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

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

View on GitHub (pinned to 4f84911bfe)