What causes "invalid npipe source, source cannot be empty" in docker/cli?

Add the Windows named-pipe path as `source:` (e.g. `\\.\\pipe\\docker_engine`).

invalid npipe source, source cannot be empty

Error message

invalid npipe source, source cannot be empty

What it means

Returned by handleNpipeToMount (cli/compose/convert/volume.go:175-176). A named-pipe mount forwards a Windows named pipe (e.g. \\.\pipe\docker_engine) into the container and therefore requires a concrete source path. An empty source makes the mount unresolvable, so it is rejected before reaching the engine.

Solutions

Add the Windows named-pipe path as `source:` (e.g. `\\.\\pipe\\docker_engine`).
Guard interpolation: `source: ${PIPE_NAME:?must be set}`.
If you are not on Windows, remove the npipe entry or gate it behind a compose profile/condition.

Example fix

# before
volumes:
  - type: npipe
    target: \\.\\pipe\\docker_engine

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

Defensive patterns

Strategy: validation

Validate before calling

for i, v := range serviceVolumes {
    if v.Type == "npipe" && strings.TrimSpace(v.Source) == "" {
        return fmt.Errorf("service volume[%d] target=%q: npipe mount requires a non-empty Windows named-pipe source", i, v.Target)
    }
}

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil && strings.Contains(err.Error(), "invalid npipe source") {
    return fmt.Errorf("compose config error: %w (set source: to a \\\\.\\\\pipe\\\\... path; guard interpolation with ${VAR:?msg})", err)
}

Prevention

npipe is Windows-only; always provide a `\\.\\pipe\\...` source.
Gate npipe entries behind a profile/condition on non-Windows hosts.
Use `${VAR:?must be set}` for interpolated pipe names so empties fail loudly.

When it happens

Trigger: ServiceVolumeConfig with Type=="npipe" and Source=="" passed to convertVolumeToMount().

Common situations: Using `type: npipe` without a `source:`; interpolation of a pipe name that resolved to empty; running an npipe entry on a non-Windows host where the path was parameterised away.

Related errors

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

Appendix: source

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

	if volume.Image != nil {
		return mount.Mount{}, errors.New("image options are incompatible with type tmpfs")
	}
	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
}

View on GitHub (pinned to 4f84911bfe)