docker/cli · error · invalidParameter
conflicting options: cannot specify both --link-local-ip and
Error message
conflicting options: cannot specify both --link-local-ip and per-network link-local IP addresses
What it means
Raised in applyContainerOptions (opts.go:827) when link-local IPs are supplied both via the --link-local-ip flag and via link-local-ip= keys in the advanced --network syntax. Both populate the endpoint's LinkLocalIPs IPAM list, so mixing the two notations is rejected as ambiguous.
Source
Thrown at cli/command/container/opts.go:828
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
}
}
if copts.ipv6Address != nil {
if ipv6, ok := netip.AddrFromSlice(copts.ipv6Address.To16()); ok {View on GitHub (pinned to e9452d6e78)
Solutions
- Move all addresses into the advanced form: --network name=mynet,link-local-ip=169.254.1.10,link-local-ip=169.254.1.11
- Or drop the per-network keys and use repeated --link-local-ip flags with a plain --network mynet
Example fix
// before docker run --link-local-ip 169.254.1.10 --network name=appnet,link-local-ip=169.254.1.11 nginx // after docker run --network name=appnet,link-local-ip=169.254.1.10,link-local-ip=169.254.1.11 nginx
When it happens
Trigger: `docker run --link-local-ip 169.254.1.10 --network name=mynet,link-local-ip=169.254.1.11 ...` — n.LinkLocalIPs non-empty while copts.linkLocalIPs also has entries.
Common situations: Niche link-local addressing setups (e.g. IPv4LL/mDNS scenarios) where commands are half-migrated to the advanced --network notation.
Related errors
- conflicting options: cannot specify both --network-alias and
- conflicting options: cannot specify both --link and per-netw
- conflicting options: cannot specify both --ip and per-networ
- conflicting options: cannot specify both --ip6 and per-netwo
- conflicting options: cannot specify both --mac-address and p
AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01).
Data as JSON: /data/errors/fdb79c38009e596f.json.
Report an issue: GitHub.