OpenNHP/opennhp · critical

udp listen ip address is incorrect

Error message

udp listen ip address is incorrect

What it means

UdpServer.Start validates config.ListenIp with net.ParseIP before binding. If the configured IP string is not a valid IP literal, startup aborts with this error. An empty ListenIp is allowed and falls back to IPv4zero (all interfaces).

Solutions

1. Set listenIp to a valid IP literal (e.g. 0.0.0.0, ::, or a specific interface IP)
2. Leave listenIp empty to listen on all interfaces
3. Use net.ParseIP on the value to verify before deploying
4. If a hostname is needed, resolve it to an IP first (or extend config to resolve)

Example fix

// before (config.toml)
listenIp = "nhp.example.com"
// after
listenIp = "0.0.0.0"

if cfg.ListenIp != "" && net.ParseIP(cfg.ListenIp) == nil {
    return fmt.Errorf("listenIp %q is not a valid IP literal", cfg.ListenIp)
}

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "ip address is incorrect") {
        return fmt.Errorf("fix listenIp in config.toml: %w", err)
    }
    return err
}

When it happens

Trigger: config.toml contains listenIp with a hostname, an invalid string like '0.0.0:9999', or a typo such as '127.0.0.1.1'.

Common situations: Operator putting a DNS name in listenIp instead of an IP; copy-paste errors in config; environment-specific config rendering mistakes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• private key parse error
• failed to create device
• server peer config invalid on initial load
• config load error
• private key parse error

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

Appendix: source

Thrown at endpoints/server/udpserver.go:240

	// load remote config,init etcd client
	err = s.initRemoteConn()
	if err == nil && s.etcdConn == nil {
		// init config
		err = s.loadBaseConfig()
	} else {
		// nhp server base config must be loaded first.
		err = s.loadRemoteBaseConfig()
	}
	if err != nil {
		return err
	}

	var netIP net.IP
	if len(s.config.ListenIp) > 0 {
		netIP = net.ParseIP(s.config.ListenIp)
		if netIP == nil {
			log.Error("udp listen ip address is incorrect!")
			return fmt.Errorf("udp listen ip address is incorrect")
		}
	} 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 {

View on GitHub (pinned to 6e04ca5ff0)