docker/compose · error

invalid ip-range: %w

Error message

invalid ip-range: %w

What it means

The IPAM pool 'ip_range' (compose: ip_range/iprang) failed netip.ParsePrefix during parseIPAMPool. Docker expects a CIDR range, not a dash range or bare address.

Source

Thrown at pkg/compose/create.go:1538

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)
			if err != nil {
				return network.IPAMConfig{}, fmt.Errorf("invalid auxiliary address: %w", err)
			}
			auxAddress[auxName] = auxAddr
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Express the range as CIDR: 172.16.0.0/24
2. For a single reserved-ish IP use a /32 (IPv4) or /128 (IPv6)
3. Ensure the range is inside the subnet and aligned to a network boundary

Example fix

# before
ip_range: 172.16.0.1-172.16.0.10
# after
ip_range: 172.16.0.0/28

if pool.IPRange != "" {
    r, err := netip.ParsePrefix(pool.IPRange)
    if err != nil { return fmt.Errorf("fix ip_range %q: %w", pool.IPRange, err) }
    if s, _ := netip.ParsePrefix(pool.Subnet); s.Bits() > 0 && !s.Contains(r.Addr()) {
        return fmt.Errorf("ip_range %s outside subnet %s", r, s)
    }
}

When it happens

Trigger: ipam: {config: [{subnet: 172.16.0.0/16, ip_range: 172.16.0.0/24}]} with any non-CIDR value, e.g. '172.16.0.5' (no prefix) or '172.16.0.1-172.16.0.10'.

Common situations: Porting dash-notation ranges from other tools or older configs; expecting ip_range to accept a single IP; host-bit-set ranges.

Related errors

• invalid subnet: %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/e84215d3e8ffec8a. Report an issue: GitHub.