volume options are incompatible with type npipe

Error message

volume options are incompatible with type npipe

What it means

Returned by handleNpipeToMount (cli/compose/convert/volume.go:178-179). Named-pipe mounts do not use named-volume options (nocopy/subpath); supplying a `volume:` block on an npipe entry is contradictory and is rejected. Note the handler intentionally allows a `bind:` block (for propagation) — only volume options are refused.

Solutions

Remove the `volume:` options block from the npipe entry.
If propagation is needed, use `bind: { propagation: ... }` (npipe accepts it) instead.

Example fix

# before
volumes:
  - type: npipe
    source: \\.\\pipe\\engine
    target: \\.\\pipe\\engine
    volume:
      nocopy: true

# after
volumes:
  - type: npipe
    source: \\.\\pipe\\engine
    target: \\.\\pipe\\engine

Defensive patterns

Strategy: validation

Validate before calling

for i, v := range serviceVolumes {
    if v.Type == "npipe" && v.Volume != nil {
        return fmt.Errorf("service volume[%d] target=%q: type npipe must not declare a volume block (use bind: for propagation)", 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 npipe") {
    return fmt.Errorf("compose config error: %w (remove the volume: block; npipe accepts bind: for propagation)", err)
}

Prevention

Remember npipe is the one non-bind type that accepts a `bind:` block (for propagation) — but never a `volume:` block.
Avoid reusing named-volume templates for npipe entries.

When it happens

Trigger: ServiceVolumeConfig with Type=="npipe" and Volume!=nil passed to convertVolumeToMount().

Common situations: Adapting a named-volume entry into an npipe entry and leaving the `volume:` block; copy-paste between definitions.

Related errors

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

Appendix: source

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

	if volume.Cluster != nil {
		return mount.Mount{}, errors.New("cluster options are incompatible with type tmpfs")
	}
	if volume.Tmpfs != nil {
		result.TmpfsOptions = &mount.TmpfsOptions{
			SizeBytes: volume.Tmpfs.Size,
		}
	}
	return result, nil
}

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

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

func handleClusterToMount(
	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,

View on GitHub (pinned to 4f84911bfe)