docker/cli · error

is not a valid mac address

Error message

%s is not a valid mac address

What it means

Returned in opts.go:352 during container-create option processing when net.ParseMAC rejects the value of the --mac-address flag. This validates the top-level container MAC address before any API call.

Solutions

1. Provide a MAC in a recognized form, e.g. 02:42:ac:11:22:33 (6 hex octets, : or - separators).
2. Double-check the octet count (6) and that all digits are hex.
3. Omit the flag to let Docker assign a MAC.

Example fix

# before
docker run --mac-address 02:42:ac:11:zz:22 alpine

# after
docker run --mac-address 02:42:ac:11:22:33 alpine

import "net"
if _, err := net.ParseMAC(strings.TrimSpace(mac)); err != nil {
    return fmt.Errorf("invalid MAC %q: %w", mac, err)
}

func validMAC(s string) bool {
    _, err := net.ParseMAC(strings.TrimSpace(s))
    return err == nil
}

// Deterministic validation error: fix the value, do not retry.
if !validMAC(mac) { /* prompt user / use default */ }

When it happens

Trigger: `docker run --mac-address <bad>` where the address is not a valid IEEE 802 MAC (wrong separator, wrong group count, non-hex digits, or out-of-range octets).

Common situations: Typo such as 02:42:ac:11:zz:22, using dashes but wrong group count, or a truncated/extra-octet address.

Related errors

• invalid range format for --expose
• network is specified multiple times
• invalid publish opts format
• invalid pull option: ' ': must be one of , or
• copying config.json into container failed

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

Appendix: source

Thrown at cli/command/container/opts.go:352

	NetworkingConfig *network.NetworkingConfig
}

// parse parses the args for the specified command and generates a Config,
// a HostConfig and returns them with the specified command.
// If the specified args are not valid, it will return an error.
//
//nolint:gocyclo
func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*containerConfig, error) {
	var (
		attachStdin  = copts.attach.Get("stdin")
		attachStdout = copts.attach.Get("stdout")
		attachStderr = copts.attach.Get("stderr")
	)

	// Validate the input mac address
	if copts.macAddress != "" {
		if _, err := net.ParseMAC(strings.TrimSpace(copts.macAddress)); err != nil {
			return nil, fmt.Errorf("%s is not a valid mac address", copts.macAddress)
		}
	}
	if copts.stdin {
		attachStdin = true
	}
	// If -a is not set, attach to stdout and stderr
	if copts.attach.Len() == 0 {
		attachStdout = true
		attachStderr = true
	}

	var err error

	swappiness := copts.swappiness
	if swappiness != -1 && (swappiness < 0 || swappiness > 100) {
		return nil, fmt.Errorf("invalid value: %d. Valid memory swappiness range is 0-100", swappiness)
	}

View on GitHub (pinned to 4f84911bfe)