What causes "failed to bind to any unicast udp port" in micro/go-micro?

Check that at least one loopback or physical interface is up (ip link / ifconfig)

failed to bind to any unicast udp port

Error message

failed to bind to any unicast udp port

What it means

During newClient, the mDNS client tries to open unicast UDP sockets on both IPv4 (udp4) and IPv6 (udp6) wildcard addresses. If both ListenUDP calls fail, no unicast socket exists and construction aborts with this error. The individual bind errors are logged beforehand at ErrorLevel.

Source

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

	closedCh  chan struct{} // TODO(reddaly): This doesn't appear to be used.
	closeLock sync.Mutex

	closed bool
}

// NewClient creates a new mdns Client that can be used to query
// for records.
func newClient() (*client, error) {
	// TODO(reddaly): At least attempt to bind to the port required in the spec.
	// Create a IPv4 listener
	uconn4, err4 := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4zero, Port: 0})
	uconn6, err6 := net.ListenUDP("udp6", &net.UDPAddr{IP: net.IPv6zero, Port: 0})
	if err4 != nil && err6 != nil {
		logger.Logf(logger.ErrorLevel, "[mdns] failed to bind to udp port: %v %v", err4, err6)
	}

	if uconn4 == nil && uconn6 == nil {
		return nil, fmt.Errorf("failed to bind to any unicast udp port")
	}

	if uconn4 == nil {
		uconn4 = &net.UDPConn{}
	}

	if uconn6 == nil {
		uconn6 = &net.UDPConn{}
	}

	mconn4, err4 := net.ListenUDP("udp4", mdnsWildcardAddrIPv4)
	mconn6, err6 := net.ListenUDP("udp6", mdnsWildcardAddrIPv6)
	if err4 != nil && err6 != nil {
		logger.Logf(logger.ErrorLevel, "[mdns] failed to bind to udp port: %v %v", err4, err6)
	}

	if mconn4 == nil && mconn6 == nil {
		return nil, fmt.Errorf("failed to bind to any multicast udp port")

View on GitHub (pinned to 24529f1404)

Solutions

Check that at least one loopback or physical interface is up (ip link / ifconfig)
Verify available file descriptors (ulimit -n) and close leaked sockets
Confirm the environment permits UDP socket creation (containers, seccomp profiles)
Inspect the preceding '[mdns] failed to bind to udp port' log lines for the underlying OS error

Example fix

// diagnose before retry
uconn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4zero, Port: 0})
if err != nil {
    log.Fatalf("cannot create UDP socket: %v — check interfaces/ulimit", err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: can we open any unicast UDP socket?
probe, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4zero, Port: 0})
if err != nil {
    log.Fatalf("unicast UDP unavailable: %v", err)
}
probe.Close()

Try / catch

c, err := mdns.NewClient(config)
if err != nil {
    if strings.Contains(err.Error(), "failed to bind to any unicast udp port") {
        // fall back to non-mdns discovery or surface a network-environment problem
        return nil, fmt.Errorf("mdns unavailable: check interfaces/fd limits: %w", err)
    }
    return nil, err
}

Prevention

Verify network interfaces are up before starting service discovery
Keep fd limits comfortably high in containers (ulimit -n)
Avoid running discovery inside sandboxes that block socket creation

When it happens

Trigger: newClient (invoked via Query or Listen) when net.ListenUDP fails for both udp4 and udp6 on port 0.

Common situations: Hosts with no network interfaces up; containers with networking disabled; resource exhaustion (out of file descriptors); sandboxed environments blocking socket creation.

Related errors

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