docker/cli · error · invalidParameterErr

conflicting options: cannot specify both --network-alias…

Error message

conflicting options: cannot specify both --network-alias and per-network alias

What it means

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.

Solutions

  1. Use only the advanced per-network alias: --network=net:alias=app.
  2. Or use only the global --network-alias=app and drop the alias from the --network value.
  3. Pick one notation consistently across your run/compose definition.

Example fix

// before
docker run --network-alias=web --network=mynet:alias=app myimage
// after
docker run --network=mynet:alias=app myimage
Defensive patterns

Strategy: validation

Validate before calling

// Reject mixing global --network-alias with per-network alias= on net #0.
if len(n.Aliases) > 0 && copts.aliases.Len() > 0 {
    return errors.New("cannot specify both --network-alias and per-network alias")
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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

Appendix: source

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

		// and only a single network is specified, omit the endpoint-configuration
		// on the client (the daemon will still create it when creating the container)
		if i == 0 && len(copts.netMode.Value()) == 1 {
			if ep == nil || reflect.ValueOf(*ep).IsZero() {
				continue
			}
		}
		endpoints[n.Target] = ep
	}
	if hasUserDefined && hasNonUserDefined {
		return nil, invalidParameter(errors.New("conflicting options: cannot attach both user-defined and non-user-defined network-modes"))
	}
	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())

View on GitHub (pinned to 4f84911bfe)