{"record":{"id":"f0ff0a332a79a9ac","repo":"docker/cli","slug":"conflicting-options-cannot-specify-both-network","errorCode":null,"errorMessage":"conflicting options: cannot specify both --network-alias and per-network alias","messagePattern":"conflicting options: cannot specify both --network-alias and per-network alias","errorType":"validation","errorClass":"invalidParameterErr","httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":813,"sourceCode":"\t\t// and only a single network is specified, omit the endpoint-configuration\n\t\t// on the client (the daemon will still create it when creating the container)\n\t\tif i == 0 && len(copts.netMode.Value()) == 1 {\n\t\t\tif ep == nil || reflect.ValueOf(*ep).IsZero() {\n\t\t\t\tcontinue\n\t\t\t}\n\t\t}\n\t\tendpoints[n.Target] = ep\n\t}\n\tif hasUserDefined && hasNonUserDefined {\n\t\treturn nil, invalidParameter(errors.New(\"conflicting options: cannot attach both user-defined and non-user-defined network-modes\"))\n\t}\n\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())","sourceCodeStart":795,"sourceCodeEnd":831,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L795-L831","documentation":"Returned by applyContainerOptions when both the global --network-alias flag (copts.aliases) and a per-network alias inside the advanced --network notation (n.Aliases) are specified for the first network (opts.go:812-814). The two alias sources are mutually exclusive for the primary network to avoid ambiguity. Marked invalidParameter.","triggerScenarios":"Running `docker run --network-alias=web --network=net:alias=app ...` where the --network value itself carries an `alias=` option and --network-alias is also present. applyContainerOptions is only applied to the first network (i==0).","commonSituations":"Mixing the legacy shorthand --network-alias with the newer advanced --network=name:alias=... notation; converting compose `aliases:` to CLI flags and leaving both forms; templating that emits both.","solutions":["Use only the advanced per-network alias: --network=net:alias=app.","Or use only the global --network-alias=app and drop the alias from the --network value.","Pick one notation consistently across your run/compose definition."],"exampleFix":"// before\ndocker run --network-alias=web --network=mynet:alias=app myimage\n// after\ndocker run --network=mynet:alias=app myimage","handlingStrategy":"validation","validationCode":"// Reject mixing global --network-alias with per-network alias= on net #0.\nif len(n.Aliases) > 0 && copts.aliases.Len() > 0 {\n    return errors.New(\"cannot specify both --network-alias and per-network alias\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Standardize on one alias notation (prefer the advanced per-network form).","Strip legacy --network-alias when migrating to --network=name:alias=...","Lint compose files for duplicate alias definitions."],"tags":["docker-cli","network","network-alias","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"}