docker/compose · error

invalid gateway address: %w

Error message

invalid gateway address: %w

What it means

The IPAM 'gateway' string failed netip.ParseAddr — it must be a plain IP address with no prefix or extra characters. The wrapped error pinpoints the offending part.

Source

Thrown at pkg/compose/create.go:1544

		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
		}

	}
	return network.IPAMConfig{
		Subnet:     subNet,
		IPRange:    ipRange,
		Gateway:    gateway,
		AuxAddress: auxAddress,

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use a bare IP: gateway: 10.0.0.1 (no /24)
2. Check for stray whitespace or quotes around the value
3. Ensure the gateway lies within the subnet

Example fix

# before
gateway: 10.0.0.1/24
# after
gateway: 10.0.0.1

if pool.Gateway != "" {
    if _, err := netip.ParseAddr(pool.Gateway); err != nil {
        return fmt.Errorf("gateway %q must be a bare IP", pool.Gateway)
    }
}

When it happens

Trigger: ipam: {config: [{subnet: 10.0.0.0/24, gateway: 10.0.0.0/24}]} or gateway: '10.0.0.' — anything that is not a bare valid IP.

Common situations: Pasting a CIDR into gateway; trailing spaces/typos; IPv6 gateway with zone or brackets.

Related errors

• invalid subnet: %w
• invalid ip-range: %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/bec7ec4830b09065. Report an issue: GitHub.