volume type must be volume, bind, tmpfs, npipe, or cluster

Error message

volume type must be volume, bind, tmpfs, npipe, or cluster

What it means

Returned by the default branch of convertVolumeToMount (cli/compose/convert/volume.go:257) when volume.Type does not match any handled case. The switch only recognises "volume", "" (treated as volume at line 244), "image", "bind", "tmpfs", "npipe", and "cluster"; anything else falls through to this catch-all. Note "image" is accepted even though no error mentions it as a default failure — only truly unknown strings reach line 257.

Solutions

Set `type:` to one of the supported lowercase values: volume, bind, tmpfs, npipe, cluster, or image.
Omit `type:` entirely if you want an anonymous named volume (defaults to "volume").
Check the docker/compose CLI version against the type you are trying to use — older builds do not recognise newer types.

Example fix

# before
volumes:
  - type: host
    source: /host/data
    target: /data

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

Defensive patterns

Strategy: type-guard

Validate before calling

// Validate every volume's type before calling convert.Volumes(...)
allowed := map[string]bool{"": true, "volume": true, "bind": true, "tmpfs": true, "npipe": true, "cluster": true, "image": true}
for i, v := range serviceVolumes {
    if !allowed[v.Type] {
        return fmt.Errorf("service volume[%d] target=%q: unsupported type %q (want volume, bind, tmpfs, npipe, cluster, image, or omitted)", i, v.Target, v.Type)
    }
}

Type guard

// isKnownVolumeType narrows a compose volume type string to the set
// accepted by convertVolumeToMount (cli/compose/convert/volume.go:243).
func isKnownVolumeType(t string) bool {
    switch t {
    case "", "volume", "image", "bind", "tmpfs", "npipe", "cluster":
        return true
    }
    return false
}

// usage:
for _, v := range serviceVolumes {
    if !isKnownVolumeType(v.Type) { /* reject early */ }
}

Try / catch

mounts, err := convert.Volumes(serviceVolumes, stackVolumes, namespace)
if err != nil && strings.Contains(err.Error(), "volume type must be volume, bind, tmpfs, npipe, or cluster") {
    return fmt.Errorf("compose config error: %w (set type: to a supported lowercase value or omit it for a named volume)", err)
}

Prevention

Always use lowercase type values — the switch is case-sensitive ("Volume" will not match).
If you omit `type:` it defaults to volume; do not invent types like "host" or "none".
Confirm the docker/compose CLI build supports the type you are using (e.g. older builds lack image/cluster).

When it happens

Trigger: A ServiceVolumeConfig whose Type is an unrecognised string (e.g. "host", "none", "Volume", "BIND", or a typo) passed to convertVolumeToMount(). Case matters: "Volume" with a capital V will not match "volume".

Common situations: Typos in `type:`; copy-pasting a non-standard type from another tool; locale/case issues ("Bind"); using a type from a newer/older compose spec than this CLI supports; leftover placeholder values like `type: TODO`.

Related errors

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

Appendix: source

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

	volume composetypes.ServiceVolumeConfig,
	stackVolumes volumes,
	namespace Namespace,
) (mount.Mount, error) {
	switch volume.Type {
	case "volume", "":
		return handleVolumeToMount(volume, stackVolumes, namespace)
	case "image":
		return handleImageToMount(volume)
	case "bind":
		return handleBindToMount(volume)
	case "tmpfs":
		return handleTmpfsToMount(volume)
	case "npipe":
		return handleNpipeToMount(volume)
	case "cluster":
		return handleClusterToMount(volume, stackVolumes, namespace)
	}
	return mount.Mount{}, errors.New("volume type must be volume, bind, tmpfs, npipe, or cluster")
}

View on GitHub (pinned to 4f84911bfe)