What causes "bad format for links: {val}" in docker/cli?

Reduce the value to at most two colon-separated parts (name:alias).

bad format for links: {val}

Error message

bad format for links: {val}

What it means

Thrown by opts.ParseLink when the input contains more than one colon (SplitN with limit 3 yields 3 parts), which is not a valid "name:alias" link. Docker link syntax allows at most one colon separating container name from alias; anything with extra colons (e.g. an IPv6-ish or scheme:host:port value) is malformed.

Source

Thrown at opts/opts.go:381

	}
	nano := cpu.Mul(cpu, big.NewRat(1e9, 1))
	if !nano.IsInt() {
		return 0, errors.New("value is too precise")
	}
	return nano.Num().Int64(), nil
}

// ParseLink parses and validates the specified string as a link format (name:alias)
func ParseLink(val string) (string, string, error) {
	if val == "" {
		return "", "", errors.New("empty string specified for links")
	}
	// We expect two parts, but restrict to three to allow detecting invalid formats.
	arr := strings.SplitN(val, ":", 3)

	// TODO(thaJeztah): clean up this logic!!
	if len(arr) > 2 {
		return "", "", errors.New("bad format for links: " + val)
	}
	// TODO(thaJeztah): this should trim the "/" prefix as well??
	if len(arr) == 1 {
		return val, val, nil
	}
	// This is kept because we can actually get a HostConfig with links
	// from an already created container and the format is not `foo:bar`
	// but `/foo:/c1/bar`
	if strings.HasPrefix(arr[0], "/") {
		// TODO(thaJeztah): clean up this logic!!
		_, alias := path.Split(arr[1])
		return arr[0][1:], alias, nil
	}
	return arr[0], arr[1], nil
}

// ValidateLink validates that the specified string has a valid link format (containerName:alias).
func ValidateLink(val string) (string, error) {

View on GitHub (pinned to 4f84911bfe)

Solutions

Reduce the value to at most two colon-separated parts (name:alias).
If you meant a single name with no alias, drop the colon entirely.
Strip any URL scheme or port suffix that introduced the extra colon.

Example fix

// before
name, alias, err := opts.ParseLink("redis:6379:db")
// after
name, alias, err := opts.ParseLink("redis:db")

Defensive patterns

Strategy: validation

Validate before calling

if strings.Count(link, ":") > 1 {
    return fmt.Errorf("link %q has too many colons; expected name:alias", link)
}
name, alias, err := opts.ParseLink(link)

Try / catch

name, alias, err := opts.ParseLink(link)
if err != nil {
    return err
}

Prevention

Validate link strings contain at most one colon before parsing.
Avoid pasting URLs or host:port specs into --link.

When it happens

Trigger: Calling opts.ParseLink("a:b:c") or any string with two or more colons. Passing --link with a value like "redis:6379:db".

Common situations: Accidentally pasting a URL or host:port spec into --link, or concatenating fields that introduce an extra colon. Legacy links also support a "/name:/container/alias" form, which is handled separately, but three plain colon-separated segments are not.

Related errors

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