What causes "invalid empty volume spec" in docker/cli?

Check for empty string before calling Parse: if spec == "" return a clear error.

invalid empty volume spec

Error message

invalid empty volume spec

What it means

Returned by volumespec.Parse (internal/volumespec/volumespec.go:25) when the input string has length 0. The parser requires at least some content to determine the volume type and target. This is the earliest possible validation failure in the volume-spec parsing pipeline.

Solutions

Check for empty string before calling Parse: if spec == "" return a clear error.
Ensure shell variables used in -v flags are set and non-empty.
Validate volume specs at configuration load time before passing to the CLI.

Example fix

// before: no guard before parsing
vol, err := volumespec.Parse(spec)

// after: validate non-empty first
if spec == "" {
    return VolumeConfig{}, fmt.Errorf("volume spec must not be empty")
}
vol, err := volumespec.Parse(spec)

Defensive patterns

Strategy: validation

Validate before calling

func parseVolumeSpec(spec string) (volumespec.VolumeConfig, error) {
    if spec == "" {
        return volumespec.VolumeConfig{}, fmt.Errorf("volume spec must not be empty")
    }
    return volumespec.Parse(spec)
}

Try / catch

vol, err := volumespec.Parse(spec)
if err != nil {
    if err.Error() == "invalid empty volume spec" {
        return fmt.Errorf("no volume path provided: specify source and/or target")
    }
    return err
}

Prevention

Check for empty string before calling volumespec.Parse.
Validate shell variables used in -v/--volume flags are set and non-empty.
Add input validation at configuration load time for volume specs from files.

When it happens

Trigger: volumespec.Parse("") is called — the spec string is empty. This can happen when a -v flag receives an empty value, a variable expansion produces an empty string, or Parse is called programmatically with an empty argument.

Common situations: Shell variable that expands to empty passed to -v (e.g., -v "$MY_VOLUME" where MY_VOLUME is unset), empty string in a compose file volume definition, programmatic Parse call with unvalidated input.

Related errors

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

Appendix: source

Thrown at internal/volumespec/volumespec.go:25

	"errors"
	"fmt"
	"slices"
	"strings"
	"unicode"
	"unicode/utf8"

	"github.com/moby/moby/api/types/mount"
)

const endOfSpec = rune(0)

// Parse parses a volume spec without any knowledge of the target platform
func Parse(spec string) (VolumeConfig, error) {
	volume := VolumeConfig{}

	switch len(spec) {
	case 0:
		return volume, errors.New("invalid empty volume spec")
	case 1, 2:
		volume.Target = spec
		volume.Type = string(mount.TypeVolume)
		return volume, nil
	}

	buffer := make([]rune, 0, len(spec))
	for _, char := range spec + string(endOfSpec) {
		switch {
		case isWindowsDrive(buffer, char):
			buffer = append(buffer, char)
		case char == ':' || char == endOfSpec:
			if err := populateFieldFromBuffer(char, buffer, &volume); err != nil {
				populateType(&volume)
				return volume, fmt.Errorf("invalid spec: %s: %w", spec, err)
			}
			buffer = buffer[:0] // reset, but reuse capacity
		default:

View on GitHub (pinned to 4f84911bfe)