docker/cli · error · invalidParameterErr

conflicting options: cannot specify both --mac-address and…

Error message

conflicting options: cannot specify both --mac-address and per-network MAC address

What it means

Returned by applyContainerOptions when both the global --mac-address flag (copts.macAddress) and a per-network MAC address inside the advanced --network notation (n.MacAddress) are specified for the first network (opts.go:824-826). Both being non-empty triggers invalidParameter. The two sources of MAC are mutually exclusive to avoid ambiguity on the primary network.

Solutions

Use only the advanced per-network MAC: --network=mynet:mac=92:d0:c6:0a:29:33.
Or use only the global --mac-address=92:d0:c6:0a:29:33 and drop mac= from the --network value.
For multiple networks, use the per-network form per target.

Example fix

// before
docker run --mac-address=92:d0:c6:0a:29:33 --network=mynet:mac=92:d0:c6:0a:29:34 myimage
// after
docker run --network=mynet:mac=92:d0:c6:0a:29:33 myimage

Defensive patterns

Strategy: validation

Validate before calling

if n.MacAddress != "" && copts.macAddress != "" {
    return errors.New("cannot specify both --mac-address and per-network MAC address")
}

Prevention

Use per-network mac= when assigning MAC on a specific network.
Remove global --mac-address when migrating to advanced notation.
Lint compose files for MAC defined both globally and per-endpoint.

When it happens

Trigger: Running `docker run --mac-address=92:d0:c6:0a:29:33 --network=mynet:mac=92:d0:c6:0a:29:34 ...` where the --network value carries a `mac=` option and the global --mac-address is also present. Applies to the first network only (i==0).

Common situations: Adopting advanced --network notation while leaving the legacy --mac-address flag; compose configs specifying MAC both globally and per-network; templating that duplicates the value.

Related errors

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

Appendix: source

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

	return endpoints, nil
}

func applyContainerOptions(n *opts.NetworkAttachmentOpts, copts *containerOptions) error { //nolint:gocyclo
	// TODO should we error if _any_ advanced option is used? (i.e. forbid to combine advanced notation with the "old" flags (`--network-alias`, `--link`, `--ip`, `--ip6`)?
	if len(n.Aliases) > 0 && copts.aliases.Len() > 0 {
		return invalidParameter(errors.New("conflicting options: cannot specify both --network-alias and per-network alias"))
	}
	if len(n.Links) > 0 && copts.links.Len() > 0 {
		return invalidParameter(errors.New("conflicting options: cannot specify both --link and per-network links"))
	}
	if n.IPv4Address.IsValid() && copts.ipv4Address != nil {
		return invalidParameter(errors.New("conflicting options: cannot specify both --ip and per-network IPv4 address"))
	}
	if n.IPv6Address.IsValid() && copts.ipv6Address != nil {
		return invalidParameter(errors.New("conflicting options: cannot specify both --ip6 and per-network IPv6 address"))
	}
	if n.MacAddress != "" && copts.macAddress != "" {
		return invalidParameter(errors.New("conflicting options: cannot specify both --mac-address and per-network MAC address"))
	}
	if len(n.LinkLocalIPs) > 0 && copts.linkLocalIPs.Len() > 0 {
		return invalidParameter(errors.New("conflicting options: cannot specify both --link-local-ip and per-network link-local IP addresses"))
	}
	if copts.aliases.Len() > 0 {
		n.Aliases = make([]string, copts.aliases.Len())
		copy(n.Aliases, copts.aliases.GetSlice())
	}
	// For a user-defined network, "--link" is an endpoint option, it creates an alias. But,
	// for the default bridge it defines a legacy-link.
	if container.NetworkMode(n.Target).IsUserDefined() && copts.links.Len() > 0 {
		n.Links = make([]string, copts.links.Len())
		copy(n.Links, copts.links.GetSlice())
	}
	if copts.ipv4Address != nil {
		if ipv4, ok := netip.AddrFromSlice(copts.ipv4Address.To4()); ok {
			n.IPv4Address = ipv4
		}

View on GitHub (pinned to 4f84911bfe)