micro/go-micro · error

failed to join multicast group on all interfaces

Error message

failed to join multicast group on all interfaces

What it means

After binding, the mDNS client calls JoinGroup on every interface for the IPv4 and IPv6 multicast groups. If joining failed on ALL interfaces for both address families, the client cannot receive multicast traffic and construction fails with this error.

Source

Thrown at internal/util/mdns/client.go:241

	ifaces, err := net.Interfaces()
	if err != nil {
		return nil, err
	}

	var errCount1, errCount2 int

	for _, iface := range ifaces {
		if err := p1.JoinGroup(&iface, &net.UDPAddr{IP: mdnsGroupIPv4}); err != nil {
			errCount1++
		}
		if err := p2.JoinGroup(&iface, &net.UDPAddr{IP: mdnsGroupIPv6}); err != nil {
			errCount2++
		}
	}

	if len(ifaces) == errCount1 && len(ifaces) == errCount2 {
		return nil, fmt.Errorf("failed to join multicast group on all interfaces")
	}

	c := &client{
		ipv4MulticastConn: mconn4,
		ipv6MulticastConn: mconn6,
		ipv4UnicastConn:   uconn4,
		ipv6UnicastConn:   uconn6,
		closedCh:          make(chan struct{}),
	}
	return c, nil
}

// Close is used to cleanup the client.
func (c *client) Close() error {
	c.closeLock.Lock()
	defer c.closeLock.Unlock()

	if c.closed {

View on GitHub (pinned to 24529f1404)

Solutions

1. Ensure at least one interface has the MULTICAST flag enabled (ip link set dev eth0 multicast on)
2. Verify the interface list is non-empty and includes a real NIC or loopback with multicast
3. Check host/VM settings that disable multicast or IPv6
4. Run with sufficient privileges (CAP_NET_RAW / not restricted by sandbox)

Example fix

// shell check before running the app
ip -o link | grep MULTICAST || ip link set dev eth0 multicast on

ifaces, _ := net.Interfaces()
multicastOK := false
for _, i := range ifaces {
    if i.Flags&net.FlagMulticast != 0 && i.Flags&net.FlagUp != 0 {
        multicastOK = true
    }
}
if !multicastOK {
    log.Fatal("no multicast-capable interface available")
}

c, err := newClient(config)
if err != nil && strings.Contains(err.Error(), "failed to join multicast group on all interfaces") {
    // degrade: use unicast discovery or polling fallback
    return nil, fmt.Errorf("multicast unsupported in this environment: %w", err)
}

When it happens

Trigger: newClient (via Query or Listen) when errCount1 and errCount2 both equal len(ifaces), i.e. JoinGroup failed for every interface on both IPv4 and IPv6.

Common situations: VMs/containers with interfaces lacking multicast capability (no MULTICAST flag); VPN or dummy interfaces only; kernels with IPv6 multicast disabled; running without needed privileges.

Related errors

• failed to join multicast group on all interfaces
• failed to bind to any multicast udp port
• failed to bind to any unicast udp port
• [ERR] mdns: Failed to bind to any udp port
• mdns: error sending multicast response: %v

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/23d56c34194aa524. Report an issue: GitHub.