docker/compose · error

invalid IPv4 address: %w

Error message

invalid IPv4 address: %w

What it means

Error "invalid IPv4 address: %w" thrown in docker/compose.

Source

Thrown at pkg/compose/create.go:494

func createEndpointSettings(p *types.Project, service types.ServiceConfig, serviceIndex int, networkKey string, links []string, useNetworkAliases bool) (*network.EndpointSettings, error) {
	const ifname = "com.docker.network.endpoint.ifname"

	config := service.Networks[networkKey]
	var ipam *network.EndpointIPAMConfig
	var (
		ipv4Address netip.Addr
		ipv6Address netip.Addr
		macAddress  string
		driverOpts  types.Options
		gwPriority  int
	)
	if config != nil {
		var err error
		if config.Ipv4Address != "" {
			ipv4Address, err = netip.ParseAddr(config.Ipv4Address)
			if err != nil {
				return nil, fmt.Errorf("invalid IPv4 address: %w", err)
			}
		}
		if config.Ipv6Address != "" {
			ipv6Address, err = netip.ParseAddr(config.Ipv6Address)
			if err != nil {
				return nil, fmt.Errorf("invalid IPv6 address: %w", err)
			}
		}
		var linkLocalIPs []netip.Addr
		for _, link := range config.LinkLocalIPs {
			if link == "" {
				continue
			}
			llIP, err := netip.ParseAddr(link)
			if err != nil {
				return nil, fmt.Errorf("invalid link-local IP: %w", err)
			}
			linkLocalIPs = append(linkLocalIPs, llIP)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Fix the ipv4_address in the network configuration to a valid IPv4 address within the network's subnet.
2. Remove the ipv4_address entry to let Docker assign one automatically.

When it happens

Trigger: A network attachment for a service specifies an ipv4_address that is not a valid IPv4 address.

Common situations: Malformed address (e.g. 300.1.2.3), an IPv6 address in the ipv4_address field, or an address outside the network's subnet.

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