docker/cli · error · invalidParameter

conflicting options: cannot specify both --ip6 and per-netwo

Error message

conflicting options: cannot specify both --ip6 and per-network IPv6 address

What it means

Raised in applyContainerOptions (opts.go:821) when a static IPv6 address is given both via --ip6 and via the per-network ip6= option in the advanced --network syntax. Only one IPv6 IPAM address per endpoint is allowed, so the duplicate specification is rejected.

Source

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

	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())
		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 {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Keep the address only in the advanced form: --network name=mynet,ip6=2001:db8::5
2. Or drop the ip6= key and use --ip6 with a plain --network mynet
3. Verify the network was created with --ipv6 and a suitable subnet

Example fix

// before
docker run --ip6 2001:db8::5 --network name=appnet,ip6=2001:db8::6 nginx
// after
docker run --network name=appnet,ip6=2001:db8::5 nginx

When it happens

Trigger: `docker run --ip6 2001:db8::5 --network name=mynet,ip6=2001:db8::6 ...` — n.IPv6Address valid while copts.ipv6Address is non-nil.

Common situations: IPv6-enabled deployments where wrapper scripts add --ip6 while the network attachment string already carries ip6=; mixed legacy/advanced notation after upgrades.

Related errors

• conflicting options: cannot specify both --ip and per-networ
• conflicting options: cannot specify both --network-alias and
• conflicting options: cannot specify both --link and per-netw
• conflicting options: cannot specify both --mac-address and p
• conflicting options: cannot specify both --link-local-ip and

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/d7dbdbba41efed70.json. Report an issue: GitHub.