{"record":{"id":"755c5d58ca373e23","repo":"OpenNHP/opennhp","slug":"listen-error-v","errorCode":null,"errorMessage":"listen error %v","messagePattern":"listen error (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"endpoints/server/udpserver.go","lineNumber":252,"sourceCode":"\n\tvar netIP net.IP\n\tif len(s.config.ListenIp) > 0 {\n\t\tnetIP = net.ParseIP(s.config.ListenIp)\n\t\tif netIP == nil {\n\t\t\tlog.Error(\"udp listen ip address is incorrect!\")\n\t\t\treturn fmt.Errorf(\"udp listen ip address is incorrect\")\n\t\t}\n\t} else {\n\t\tnetIP = net.IPv4zero // will both listen on ipv4 0.0.0.0:port and ipv6 [::]:port\n\t}\n\n\ts.listenConn, err = net.ListenUDP(\"udp\", &net.UDPAddr{\n\t\tIP:   netIP,\n\t\tPort: s.config.ListenPort,\n\t})\n\tif err != nil {\n\t\tlog.Error(\"listen error: %v\", err)\n\t\treturn fmt.Errorf(\"listen error %v\", err)\n\t}\n\n\t// retrieve local port\n\tladdr := s.listenConn.LocalAddr()\n\ts.listenAddr, err = net.ResolveUDPAddr(laddr.Network(), laddr.String())\n\tif err != nil {\n\t\tlog.Error(\"resolve local UDPAddr error: %v\", err)\n\t\treturn fmt.Errorf(\"resolve UDPAddr error %v\", err)\n\t}\n\n\tprk, err := base64.StdEncoding.DecodeString(s.config.PrivateKeyBase64)\n\tif err != nil {\n\t\tlog.Error(\"private key parse error: %v\", err)\n\t\treturn fmt.Errorf(\"private key parse error %v\", err)\n\t}\n\n\toption := &core.DeviceOptions{\n\t\tDisableAgentPeerValidation: s.config.DisableAgentValidation,","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/OpenNHP/opennhp/blob/6e04ca5ff03222a699c24205cd4bf8fee9af7ffe/endpoints/server/udpserver.go#L234-L270","documentation":"net.ListenUDP failed while binding the configured IP:port, so Start aborts with this error wrapping the OS error. Common causes are port already in use, binding an IP not assigned to the host, or lacking privileges for low ports.","triggerScenarios":"Another process (or a previous un-terminated instance) already holds ListenPort; ListenIp is not a local interface address; port <1024 without CAP_NET_BIND_SERVICE/root.","commonSituations":"Duplicate daemon instance after a failed restart; Docker/network namespace port conflicts; config pointing at a container-internal IP that doesn't exist in the host namespace.","solutions":["Check the port with ss -ulpn | grep <port> and stop the conflicting process","Change listenPort in config.toml to a free port","Verify listenIp is an IP assigned to a local interface","Run as root or grant CAP_NET_BIND_SERVICE for privileged ports","Wait for TIME_WAIT/lingering socket release and retry"],"exampleFix":"// before (config.toml)\nlistenPort = 62302 // already bound by old instance\n// after\nlistenPort = 62303","handlingStrategy":"retry","validationCode":"conn, err := net.ListenPacket(\"udp\", fmt.Sprintf(\"%s:%d\", cfg.ListenIp, cfg.ListenPort))\nif err != nil { return fmt.Errorf(\"port unavailable: %w\", err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"if err := server.Start(); err != nil {\n    if strings.Contains(err.Error(), \"listen error\") {\n        time.Sleep(retryDelay)\n        return server.Start()\n    }\n    return err\n}","preventionTips":["Check port availability with ss -ulpn before start","Ensure only one daemon instance runs per host","Use ports >1024 or grant CAP_NET_BIND_SERVICE","Verify listenIp matches a local interface IP in the runtime namespace"],"tags":["udp","bind","network","startup"],"backgroundTag":"address-already-in-use","analyzedSha":"6e04ca5ff03222a699c24205cd4bf8fee9af7ffe","analyzedAt":"2026-09-07T15:44:59.941Z","contentChangedAt":"2026-09-07T15:44:59.941Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}