{"record":{"id":"f5817d00af83882d","repo":"docker/cli","slug":"conflicting-options-cannot-specify-both-mac-add","errorCode":null,"errorMessage":"conflicting options: cannot specify both --mac-address and per-network MAC address","messagePattern":"conflicting options: cannot specify both --mac-address and per-network MAC address","errorType":"validation","errorClass":"invalidParameterErr","httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":825,"sourceCode":"\treturn endpoints, nil\n}\n\nfunc applyContainerOptions(n *opts.NetworkAttachmentOpts, copts *containerOptions) error { //nolint:gocyclo\n\t// 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`)?\n\tif len(n.Aliases) > 0 && copts.aliases.Len() > 0 {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --network-alias and per-network alias\"))\n\t}\n\tif len(n.Links) > 0 && copts.links.Len() > 0 {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --link and per-network links\"))\n\t}\n\tif n.IPv4Address.IsValid() && copts.ipv4Address != nil {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --ip and per-network IPv4 address\"))\n\t}\n\tif n.IPv6Address.IsValid() && copts.ipv6Address != nil {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --ip6 and per-network IPv6 address\"))\n\t}\n\tif n.MacAddress != \"\" && copts.macAddress != \"\" {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --mac-address and per-network MAC address\"))\n\t}\n\tif len(n.LinkLocalIPs) > 0 && copts.linkLocalIPs.Len() > 0 {\n\t\treturn invalidParameter(errors.New(\"conflicting options: cannot specify both --link-local-ip and per-network link-local IP addresses\"))\n\t}\n\tif copts.aliases.Len() > 0 {\n\t\tn.Aliases = make([]string, copts.aliases.Len())\n\t\tcopy(n.Aliases, copts.aliases.GetSlice())\n\t}\n\t// For a user-defined network, \"--link\" is an endpoint option, it creates an alias. But,\n\t// for the default bridge it defines a legacy-link.\n\tif container.NetworkMode(n.Target).IsUserDefined() && copts.links.Len() > 0 {\n\t\tn.Links = make([]string, copts.links.Len())\n\t\tcopy(n.Links, copts.links.GetSlice())\n\t}\n\tif copts.ipv4Address != nil {\n\t\tif ipv4, ok := netip.AddrFromSlice(copts.ipv4Address.To4()); ok {\n\t\t\tn.IPv4Address = ipv4\n\t\t}","sourceCodeStart":807,"sourceCodeEnd":843,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L807-L843","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ndocker run --mac-address=92:d0:c6:0a:29:33 --network=mynet:mac=92:d0:c6:0a:29:34 myimage\n// after\ndocker run --network=mynet:mac=92:d0:c6:0a:29:33 myimage","handlingStrategy":"validation","validationCode":"if n.MacAddress != \"\" && copts.macAddress != \"\" {\n    return errors.New(\"cannot specify both --mac-address and per-network MAC address\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["docker-cli","network","mac-address","conflicting-options","validation","container-create"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}