docker/compose · error

invalid auxiliary address: %w

Error message

invalid auxiliary address: %w

What it means

One of the IPAM aux_addresses (compose: ipam.config.aux_addresses / auxiliary addresses) failed netip.ParseAddr. Each value must be a plain IP address keyed by a label (e.g. {host1: 10.0.0.5}).

Source

Thrown at pkg/compose/create.go:1552

	}
	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,
	}, nil
}

func parseMACAddr(macAddress string) (network.HardwareAddr, error) {
	if macAddress == "" {
		return nil, nil
	}
	m, err := net.ParseMAC(macAddress)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Use bare IPs only: aux_addresses: {host1: 10.0.0.5}
2. Use DNS/aliases (networks.<net>.aliases) for hostname-style entries
3. Verify each address is inside the subnet

Example fix

# before
aux_addresses:
  host1: db.internal
# after
aux_addresses:
  host1: 10.0.0.5

for k, v := range pool.AuxiliaryAddresses {
    if _, err := netip.ParseAddr(v); err != nil {
        return fmt.Errorf("aux address %s=%q must be a bare IP", k, v)
    }
}

When it happens

Trigger: aux_addresses: {host1: 10.0.0.5/32} or any non-IP value like a hostname ('db.internal') in the aux address map.

Common situations: Confusing aux addresses with DNS names or hostnames; pasting CIDRs; IPv6 with brackets.

Related errors

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