docker/compose · error

invalid link-local IP: %w

Error message

invalid link-local IP: %w

What it means

Error "invalid link-local IP: %w" thrown in docker/compose.

Source

Thrown at pkg/compose/create.go:510

			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)
		}

		ipam = &network.EndpointIPAMConfig{
			IPv4Address:  ipv4Address.Unmap(),
			IPv6Address:  ipv6Address,
			LinkLocalIPs: linkLocalIPs,
		}
		macAddress = config.MacAddress
		driverOpts = config.DriverOpts
		if config.InterfaceName != "" {
			if driverOpts == nil {
				driverOpts = map[string]string{}
			}
			if name, ok := driverOpts[ifname]; ok && name != config.InterfaceName {
				logrus.Warnf("ignoring services.%s.networks.%s.interface_name as %s driver_opts is already declared", service.Name, networkKey, ifname)
			}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Correct each entry in link_local_ips to a valid address in the 169.254.0.0/16 (or fe80::/10) range.
2. Remove the invalid link_local_ips entries.

When it happens

Trigger: A link-local IP entry in the service's network configuration cannot be parsed as a valid IP address.

Common situations: Typo in a link_local_ip value, a hostname instead of an IP, or a value outside the 169.254.0.0/16 (or fe80::/10) range.

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