What causes "too many colons" in docker/cli?

too many colons

Error message

too many colons

What it means

Returned by populateFieldFromBuffer (internal/volumespec/volumespec.go:72) when a third colon is encountered in the volume spec after source and target have already been populated. Docker volume specs support at most three colon-separated segments (source:target:options); encountering a fourth delimiter is invalid.

Solutions

Reduce to at most three colon-separated segments: source:target:options.
Use commas within the options segment instead of colons for multiple options (e.g., 'src:dst:ro,nocopy' not 'src:dst:ro:nocopy').

Example fix

// before: too many colons
// docker run -v /a:/b:ro:nocopy nginx

// after: comma-separated options
// docker run -v /a:/b:ro,nocopy nginx

Defensive patterns

Strategy: validation

Validate before calling

func validateVolumeColonCount(spec string) error {
    // Windows drive letters (e.g., C:) are handled by the parser, but
    // a spec with more than 2 meaningful colons is invalid.
    if strings.Count(spec, ":") > 3 {
        return fmt.Errorf("too many colons in volume spec: %s (max source:target:options)", spec)
    }
    return nil
}

Try / catch

vol, err := volumespec.Parse(spec)
if err != nil {
    if err.Error() == "too many colons" {
        return fmt.Errorf("volume spec %q has too many colons; use format source:target:options with comma-separated options", spec)
    }
    return err
}

Prevention

Limit volume specs to at most three colon-separated segments: source:target:options.
Use commas within the options segment for multiple options (e.g., ro,nocopy).
Be aware that Windows drive letters (C:) are treated specially by the parser.

When it happens

Trigger: volumespec.Parse is called with a spec containing more than two colons in a meaningful position, e.g., '/a:/b:ro:extra'. After source, target, and options are set, the parser encounters another ':' and returns this error.

Common situations: Typo adding extra colons, misunderstanding the volume spec format (attempting to specify multiple option groups with colons instead of commas), Windows drive letters interacting with colon parsing in unexpected ways.

Related errors

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

Appendix: source

Thrown at internal/volumespec/volumespec.go:72

}

func populateFieldFromBuffer(char rune, buffer []rune, volume *VolumeConfig) error {
	strBuffer := string(buffer)
	switch {
	case len(buffer) == 0:
		return errors.New("empty section between colons")
	// Anonymous volume
	case volume.Source == "" && char == endOfSpec:
		volume.Target = strBuffer
		return nil
	case volume.Source == "":
		volume.Source = strBuffer
		return nil
	case volume.Target == "":
		volume.Target = strBuffer
		return nil
	case char == ':':
		return errors.New("too many colons")
	}
	for option := range strings.SplitSeq(strBuffer, ",") {
		switch option {
		case "ro":
			volume.ReadOnly = true
		case "rw":
			volume.ReadOnly = false
		case "nocopy":
			volume.Volume = &VolumeOpts{NoCopy: true}
		default:
			if isBindOption(option) {
				volume.Bind = &BindOpts{Propagation: option}
			}
			// ignore unknown options
		}
	}
	return nil
}

View on GitHub (pinned to 4f84911bfe)