docker/cli · error

IP address is not correctly formatted

Error message

IP address is not correctly formatted: %s

What it means

Returned by ValidateIPAddress (opts/opts.go:192) when net.ParseIP cannot parse the (trimmed) input as an IPv4 or IPv6 address. ValidateIPAddress returns the normalized canonical form on success and is used as a ListOpts validator and by ValidateExtraHost. It explicitly rejects bracketed IPv6 forms like `[::1]` (callers must strip brackets first).

Solutions

1. Provide a full IPv4 (127.0.0.1) or IPv6 (::1) literal.
2. Strip surrounding square brackets before calling: input `[::1]` becomes `::1`.
3. Resolve hostnames to IPs yourself first; this function does not do DNS.
4. Trim leading/trailing whitespace (the function trims internally, but confirm no other stray characters).

Example fix

// before
v, err := opts.ValidateIPAddress("[::1]")

// after
v, err := opts.ValidateIPAddress("::1")

func isValidIP(val string) bool {
    return net.ParseIP(strings.TrimSpace(strings.Trim(val, "[]"))) != nil
}

// isIPAddress narrows a string to a valid normalized IP in Go (returns canonical form).
func isIPAddress(val string) (string, bool) {
    if ip := net.ParseIP(strings.TrimSpace(val)); ip != nil {
        return ip.String(), true
    }
    return "", false
}

if _, err := opts.ValidateIPAddress(val); err != nil {
    return fmt.Errorf("invalid IP %q: %w", val, err)
}

When it happens

Trigger: Calling ValidateIPAddress with a non-IP string: a hostname, a truncated address (`127.0.0`), an out-of-range octet (`999.0.0.1`), or `[::1]` with brackets intact. Also fires indirectly wherever this is a validator (e.g. --ip / --ip6-style lists if wired up).

Common situations: Passing a DNS name where an IP is required, partial IPv6, or carrying brackets from a copy-pasted URL.

Related errors

• invalid gw-priority ( )
• invalid IP address in add-host
• invalid field
• conflicting options: cannot attach both user-defined and…
• conflicting options: cannot specify both --network-alias…

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

Appendix: source

Thrown at opts/opts.go:192

}

// ValidatorFctType defines a validator function that returns a validated string and/or an error.
type ValidatorFctType func(val string) (string, error)

// ValidatorFctListType defines a validator function that returns a validated list of string and/or an error
type ValidatorFctListType func(val string) ([]string, error)

// ValidateIPAddress validates if the given value is a correctly formatted
// IP address, and returns the value in normalized form. Leading and trailing
// whitespace is allowed, but it does not allow IPv6 addresses surrounded by
// square brackets ("[::1]").
//
// Refer to [net.ParseIP] for accepted formats.
func ValidateIPAddress(val string) (string, error) {
	if ip := net.ParseIP(strings.TrimSpace(val)); ip != nil {
		return ip.String(), nil
	}
	return "", fmt.Errorf("IP address is not correctly formatted: %s", val)
}

// ValidateMACAddress validates a MAC address.
//
// Deprecated: use [net.ParseMAC]. This function will be removed in the next release.
func ValidateMACAddress(val string) (string, error) {
	_, err := net.ParseMAC(strings.TrimSpace(val))
	if err != nil {
		return "", err
	}
	return val, nil
}

// ValidateDNSSearch validates domain for resolvconf search configuration.
// A zero length domain is represented by a dot (.).
func ValidateDNSSearch(val string) (string, error) {
	if val = strings.Trim(val, " "); val == "." {
		return val, nil

View on GitHub (pinned to 4f84911bfe)