cannot configure multiple gateways

Error message

cannot configure multiple gateways (%s, %s) for the same subnet (%s)

What it means

Returned by createIPAMConfig when consolidating IPAM gateway configuration during `docker network create`. Each subnet may have at most one gateway; once a gateway IP is assigned to a subnet's IPAMConfig (iData[s].Gateway.IsValid()), attempting to assign a second gateway whose IP falls inside the same subnet triggers this error. It enforces the 1:1 subnet-to-gateway invariant the daemon's IPAM driver expects.

Solutions

Remove duplicate --gateway flags so each subnet has exactly one gateway.
If you need two gateways, put them on two distinct non-overlapping --subnet declarations (e.g. separate IPv4 and IPv6 subnets).
Let IPAM auto-assign the gateway by omitting --gateway entirely for subnets that do not need an explicit one.

Example fix

// before
docker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 --gateway 172.20.0.2 net
// after
docker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 net

Defensive patterns

Strategy: validation

Validate before calling

// Before building the create request, ensure at most one gateway per subnet.
func validateGateways(subnets []string, gateways []net.IP) error {
    type seen struct{}
    assigned := make(map[string]seen) // subnet string -> has gateway
    for _, s := range subnets {
        _, ipn, err := net.ParseCIDR(s)
        if err != nil { return err }
        for _, g := range gateways {
            if ipn.Contains(g) {
                if _, ok := assigned[s]; ok {
                    return fmt.Errorf("subnet %s already has a gateway", s)
                }
                assigned[s] = seen{}
            }
        }
    }
    return nil
}

Prevention

Maintain one --gateway per --subnet; track them in a single config structure.
When scripting, build a map[subnet]gateway and error on duplicate keys before invoking docker.
Prefer omitting --gateway to let IPAM auto-assign unless you need a specific address.

When it happens

Trigger: Passing two or more --gateway flags where the supplied gateway IPs both resolve (via subnetMatches) to the same --subnet. For example: `docker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 --gateway 172.20.0.2 net`. The second gateway hits iData[s].Gateway.IsValid()==true at create.go:204.

Common situations: Mistakenly specifying both an IPv4 and IPv6 gateway for the same CIDR, copy-pasting a gateway flag twice, or assuming the second --gateway replaces rather than augments the first. Also occurs when overlapping subnets are intended but the user forgets that gateways are matched by containment.

Related errors

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

Appendix: source

Thrown at cli/command/network/create.go:205

		}
		if !match {
			return nil, fmt.Errorf("no matching subnet for range %s", r.String())
		}
	}

	// Validate and add valid gateways
	for _, g := range options.gateways {
		match := false
		for _, s := range options.subnets {
			ok, err := subnetMatches(s, g.String())
			if err != nil {
				return nil, err
			}
			if !ok {
				continue
			}
			if iData[s].Gateway.IsValid() {
				return nil, fmt.Errorf("cannot configure multiple gateways (%s, %s) for the same subnet (%s)", g, iData[s].Gateway, s)
			}
			d := iData[s]
			d.Gateway = toNetipAddr(g)
			match = true
		}
		if !match {
			return nil, fmt.Errorf("no matching subnet for gateway %s", g)
		}
	}

	// Validate and add aux-addresses
	for name, aa := range options.auxAddresses.GetAll() {
		if aa == "" {
			continue
		}
		auxAddr, err := netip.ParseAddr(aa)
		if err != nil {
			return nil, err

View on GitHub (pinned to 4f84911bfe)