OpenNHP/opennhp · error

resolve UDPAddr error

Error message

resolve UDPAddr error %v

What it means

After a successful ListenUDP, Start resolves the local address back into a *net.UDPAddr and stores it as s.listenAddr. Failure of net.ResolveUDPAddr here is unexpected (the kernel just reported a valid socket), so this error indicates an internal anomaly in address parsing.

Solutions

1. Retry startup; this is typically transient or environment-specific
2. Log and inspect laddr.String() and laddr.Network() to see what failed to parse
3. Upgrade Go runtime if the OS returns an unusual address format
4. Report upstream with the OS and address string if reproducible

Example fix

// debug aid
log.Info("local addr: network=%s string=%s", laddr.Network(), laddr.String())

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "resolve UDPAddr error") {
        return retryWithBackoff(server.Start, 3)
    }
    return err
}

When it happens

Trigger: net.ResolveUDPAddr fails on the string returned by listenConn.LocalAddr(), e.g. malformed or unsupported network/address string from the OS.

Common situations: Rare; exotic platforms or environments returning unusual LocalAddr formats; usually indicates a Go runtime/OS-level quirk rather than user misconfiguration.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• udp listen ip address is incorrect
• listen error
• private key parse error
• failed to create device
• server peer config invalid on initial load

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/414d26dba2909a1b. Report an issue: GitHub.

Appendix: source

Thrown at endpoints/server/udpserver.go:260

	} else {
		netIP = net.IPv4zero // will both listen on ipv4 0.0.0.0:port and ipv6 [::]:port
	}

	s.listenConn, err = net.ListenUDP("udp", &net.UDPAddr{
		IP:   netIP,
		Port: s.config.ListenPort,
	})
	if err != nil {
		log.Error("listen error: %v", err)
		return fmt.Errorf("listen error %v", err)
	}

	// retrieve local port
	laddr := s.listenConn.LocalAddr()
	s.listenAddr, err = net.ResolveUDPAddr(laddr.Network(), laddr.String())
	if err != nil {
		log.Error("resolve local UDPAddr error: %v", err)
		return fmt.Errorf("resolve UDPAddr error %v", err)
	}

	prk, err := base64.StdEncoding.DecodeString(s.config.PrivateKeyBase64)
	if err != nil {
		log.Error("private key parse error: %v", err)
		return fmt.Errorf("private key parse error %v", err)
	}

	option := &core.DeviceOptions{
		DisableAgentPeerValidation: s.config.DisableAgentValidation,
	}
	s.device = core.NewDevice(core.NHP_SERVER, prk, option)
	if s.device == nil {
		log.Critical("failed to create device: %v", err)
		return fmt.Errorf("failed to create device %v", err)
	}

	// Stateless cookie signing key. In a multi-instance cluster all

View on GitHub (pinned to 6e04ca5ff0)