docker/cli · error · invalidParameter

conflicting options: cannot attach both user-defined and non

Error message

conflicting options: cannot attach both user-defined and non-user-defined network-modes

What it means

parseNetworkOpts iterates every --network attachment and classifies each as user-defined (a named custom network) or non-user-defined (built-in modes like host, none, bridge, or container:<id>); if both classes appear it returns this invalid-parameter error (opts.go:770-806). Built-in modes define the container's whole network sandbox, so they cannot coexist with attachments to additional user-defined networks.

Source

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

		if err != nil {
			return nil, err
		}
		if _, ok := endpoints[n.Target]; ok {
			return nil, invalidParameter(fmt.Errorf("network %q is specified multiple times", n.Target))
		}

		// For backward compatibility: if no custom options are provided for the network,
		// 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"))
	}

View on GitHub (pinned to e9452d6e78)

Solutions

  1. Pick one category: either a single built-in mode (host/none/container:<id>) or one-or-more user-defined networks
  2. To reach services on a user-defined network, drop --network host and attach only to the custom network, publishing ports as needed
  3. If a container truly needs another network later, use `docker network connect <net> <container>` after creation with a compatible mode

Example fix

# before
docker run --network host --network mynet myimage
# after
docker run --network mynet -p 8080:8080 myimage

When it happens

Trigger: Passing --network more than once mixing categories, e.g. `docker run --network host --network mynet image`, `--network=container:web --network=backend`, or `--network none --network bridge` combined with a custom network. Multiple user-defined networks together are accepted by the CLI (though older daemons may reject >1 at create).

Common situations: Trying to give a host-networked container access to a custom bridge network too; compose-style multi-network thinking applied to docker run with one of the networks being `host`; scripts appending a default `--network host` while the user adds their own network.

Related errors

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