docker/cli · error

no matching subnet for gateway

Error message

no matching subnet for gateway %s

What it means

Returned by createIPAMConfig when a --gateway IP does not fall inside any of the configured --subnet CIDRs. The loop at create.go:194-213 iterates all subnets and sets match=true only when subnetMatches returns true; if no subnet contains the gateway, the command fails. This prevents handing the daemon a gateway that belongs to no managed address space.

Solutions

1. Verify the gateway IP is numerically contained in one of the --subnet CIDRs.
2. Add the missing --subnet that contains the intended gateway.
3. Drop the explicit --gateway and let IPAM pick the first usable host address automatically.

Example fix

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

// Verify every gateway is contained in some declared subnet.
func gatewaysHaveSubnets(subnets []string, gateways []net.IP) error {
    nets := make([]*net.IPNet, 0, len(subnets))
    for _, s := range subnets {
        _, ipn, err := net.ParseCIDR(s)
        if err != nil { return err }
        nets = append(nets, ipn)
    }
    for _, g := range gateways {
        ok := false
        for _, ipn := range nets {
            if ipn.Contains(g) { ok = true; break }
        }
        if !ok { return fmt.Errorf("no subnet contains gateway %s", g) }
    }
    return nil
}

When it happens

Trigger: Supplying a --gateway whose address is outside every --subnet. For example: `docker network create --subnet 172.20.0.0/16 --gateway 10.0.0.1 net`, or specifying only --gateway without a matching --subnet.

Common situations: CIDR prefix typos (wrong octet), copying a gateway from another network's config, mixing up which subnet a gateway belongs to, or forgetting to declare the IPv6 subnet when adding an IPv6 gateway.

Related errors

• cannot configure multiple gateways
• cannot configure multiple ranges
• no matching subnet for range
• no matching subnet for aux-address
• invalid subnet

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

Appendix: source

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

	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
		}
		match := false
		for _, s := range options.subnets {
			ok, err := subnetMatches(s, auxAddr.String())
			if err != nil {
				return nil, err
			}

View on GitHub (pinned to 4f84911bfe)