docker/cli · error · invalidParameterErr

conflicting options: cannot attach both user-defined and…

Error message

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

What it means

Returned by parseNetworkOpts when the set of --network targets mixes at least one user-defined network (a named network like "my-net") with at least one non-user-defined mode ("bridge", "host", "none", "container:...") (opts.go:770-806). hasUserDefined and hasNonUserDefined both becoming true triggers invalidParameter. The check iterates copts.netMode.Value() and tests each Target with container.NetworkMode.IsUserDefined().

Solutions

  1. Use only user-defined networks when attaching to multiple: --network my-net --network my-net2.
  2. Drop the builtin mode (--network host/bridge/none) from the multi-network command.
  3. If you need host networking, attach only to host (single network).

Example fix

// before
docker run --network app-net --network host myimage
// after
docker run --network app-net myimage
Defensive patterns

Strategy: validation

Validate before calling

// Ensure all --network targets are the same class before invoking.
var hasUD, hasNonUD bool
for _, n := range copts.netMode.Value() {
    if container.NetworkMode(n.Target).IsUserDefined() {
        hasUD = true
    } else {
        hasNonUD = true
    }
}
if hasUD && hasNonUD {
    return errors.New("cannot mix user-defined and builtin network modes")
}

Prevention

When it happens

Trigger: Running `docker run --network my-net --network host ...` or `--network bridge --network my-net ...` or `--network my-net --network none ...`. Any combination where one Target is a custom network name and another is a builtin mode.

Common situations: Migrating from a single --network to multi-network attach and leaving a leftover --network=bridge; compose-style configs flattening into multiple --network flags; assuming builtin modes can be combined with user-defined networks in one run.

Related errors

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

Appendix: 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 4f84911bfe)