docker/compose · error

invalid IPv6 address: %w

Error message

invalid IPv6 address: %w

What it means

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

Source

Thrown at pkg/compose/create.go:500

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

		ipam = &network.EndpointIPAMConfig{
			IPv4Address:  ipv4Address.Unmap(),
			IPv6Address:  ipv6Address,
			LinkLocalIPs: linkLocalIPs,

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Fix the ipv6_address in the network configuration to a valid IPv6 address within the network's subnet, and ensure enable_ipv6 is set on the network.
2. Remove the ipv6_address entry to let Docker assign one automatically.

When it happens

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

Common situations: Malformed IPv6 literal, an IPv4 address in the ipv6_address field, or IPv6 used on a network without IPv6 enabled.

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