docker/cli · error

no matching subnet for aux-address

Error message

no matching subnet for aux-address %s

What it means

Returned by createIPAMConfig when an --aux-address value does not lie within any configured --subnet. Like gateways, aux-addresses are matched against subnets by containment (create.go:217-239); an aux address that matches no subnet produces this error so the daemon never receives an auxiliary address outside its managed ranges.

Solutions

  1. Confirm each --aux-address IP belongs to one of the declared --subnet CIDRs.
  2. Add or correct the --subnet so it covers the auxiliary address.
  3. Remove stale --aux-address entries inherited from another network's template.

Example fix

// before
docker network create --subnet 172.20.0.0/16 --aux-address dns=10.0.0.9 net
// after
docker network create --subnet 172.20.0.0/16 --aux-address dns=172.20.0.9 net
Defensive patterns

Strategy: validation

Validate before calling

// Check each aux-address IP is within a declared subnet.
func auxAddressesHaveSubnets(subnets []string, aux map[string]string) 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 name, ip := range aux {
        parsed := net.ParseIP(ip)
        if parsed == nil { return fmt.Errorf("bad aux ip %s", ip) }
        ok := false
        for _, ipn := range nets { if ipn.Contains(parsed) { ok = true; break } }
        if !ok { return fmt.Errorf("no subnet for aux-address %s (%s)", name, ip) }
    }
    return nil
}

Prevention

When it happens

Trigger: Passing `--aux-address name=IP` where IP is not contained by any --subnet. Example: `docker network create --subnet 172.20.0.0/16 --aux-address dns=10.0.0.9 net`. Also triggered when an aux-address is given with no --subnet at all.

Common situations: Network driver expecting aux addresses (e.g. overlay/macvlan) but the operator reuses IPs from a different network, or a subnet was changed and the aux addresses were not updated to match.

Related errors

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

Appendix: source

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

		}
		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
			}
			if !ok {
				continue
			}
			iData[s].AuxAddress[name] = auxAddr
			match = true
		}
		if !match {
			return nil, fmt.Errorf("no matching subnet for aux-address %s", aa)
		}
	}

	idl := make([]network.IPAMConfig, 0, len(iData))
	for _, v := range iData {
		idl = append(idl, *v)
	}

	return &network.IPAM{
		Driver:  options.driver,
		Config:  idl,
		Options: options.driverOpts.GetAll(),
	}, nil
}

func subnetMatches(subnet, data string) (bool, error) {
	var ip net.IP

View on GitHub (pinned to 4f84911bfe)