docker/compose · error

invalid subnet: %w

Error message

invalid subnet: %w

What it means

An IPAM pool 'subnet' string in the compose network config could not be parsed as an CIDR prefix (netip.ParsePrefix). It wraps the parser error, so the message includes the exact position/reason (e.g. missing netmask, host bits set, malformed octets).

Source

Thrown at pkg/compose/create.go:1532

		s.events.On(errorEvent(eventName, err.Error()))
		return err
	}
	s.events.On(createdEvent(eventName))
	return nil
}

func parseIPAMPool(pool *types.IPAMPool) (network.IPAMConfig, error) {
	var (
		err        error
		subNet     netip.Prefix
		ipRange    netip.Prefix
		gateway    netip.Addr
		auxAddress map[string]netip.Addr
	)
	if pool.Subnet != "" {
		subNet, err = netip.ParsePrefix(pool.Subnet)
		if err != nil {
			return network.IPAMConfig{}, fmt.Errorf("invalid subnet: %w", err)
		}
	}
	if pool.IPRange != "" {
		ipRange, err = netip.ParsePrefix(pool.IPRange)
		if err != nil {
			return network.IPAMConfig{}, fmt.Errorf("invalid ip-range: %w", err)
		}
	}
	if pool.Gateway != "" {
		gateway, err = netip.ParseAddr(pool.Gateway)
		if err != nil {
			return network.IPAMConfig{}, fmt.Errorf("invalid gateway address: %w", err)
		}
	}
	if len(pool.AuxiliaryAddresses) > 0 {
		auxAddress = make(map[string]netip.Addr, len(pool.AuxiliaryAddresses))
		for auxName, addr := range pool.AuxiliaryAddresses {
			auxAddr, err := netip.ParseAddr(addr)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use full CIDR with network address: 172.16.0.0/16, not .1
2. For IPv6 include the prefix: fd00:dead:beef::/64
3. If you meant a subset of a subnet, use ip_range instead
4. Validate with a quick parse before running compose

Example fix

# before
subnet: 172.16.0.1/16
# after
subnet: 172.16.0.0/16
# gateway goes in its own field:
gateway: 172.16.0.1

for _, pool := range net.IPAM.Config {
    if pool.Subnet != "" {
        if _, err := netip.ParsePrefix(pool.Subnet); err != nil {
            return fmt.Errorf("fix subnet %q: %w", pool.Subnet, err)
        }
    }
}

When it happens

Trigger: networks: x: {ipam: {config: [{subnet: 172.16.0.1}]}} — any subnet value that is not a valid CIDR like 172.16.0.0/16; also host bits set (172.16.0.1/16) which netip rejects.

Common situations: Using a gateway address as the subnet; forgetting the /prefix; typo'd IPv6 subnet; copying a range ('172.16.0.0-172.16.0.255') which is not CIDR syntax.

Related errors

• invalid ip-range: %w
• invalid gateway address: %w
• invalid auxiliary address: %w
• unsupported protocol for address: %s
• unsupported network: %s

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/b205d4f2907b4a16. Report an issue: GitHub.