{"record":{"id":"de8a2f1790de8f13","repo":"XTLS/Xray-core","slug":"failed-to-create-udp-listener","errorCode":null,"errorMessage":"failed to create UDP listener","messagePattern":"failed to create UDP listener","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"proxy/socks/protocol.go","lineNumber":208,"sourceCode":"\t}\n\trequest.Address = addr\n\trequest.Port = port\n\n\tresponseAddress := s.address\n\tresponsePort := s.port\n\tvar tempUDPConn *TempUDPConn\n\t//nolint:gocritic // Use if else chain for clarity\n\tif request.Command == protocol.RequestCommandUDP {\n\t\tif s.config.Address != nil {\n\t\t\t// Use configured IP as remote address in the response to UDP Associate\n\t\t\tresponseAddress = s.config.Address.AsAddress()\n\t\t} else {\n\t\t\t// Use conn.LocalAddr() IP as remote address in the response by default\n\t\t\tresponseAddress = s.localAddress\n\t\t}\n\t\tudpHub, err := internet.ListenSystemPacket(context.Background(), &net.UDPAddr{IP: responseAddress.IP(), Port: 0}, nil)\n\t\tif err != nil {\n\t\t\treturn nil, nil, errors.New(\"failed to create UDP listener\").Base(err)\n\t\t}\n\t\tresponsePort = net.Port(udpHub.LocalAddr().(*net.UDPAddr).Port)\n\t\texpectedRemote := &gonet.UDPAddr{}\n\t\t// UDP Associate should not specify a domain as source IP\n\t\tif request.Address.Family().IsDomain() || request.Address.IP().IsUnspecified() {\n\t\t\texpectedRemote.IP = writer.RemoteAddr().(*net.TCPAddr).IP // unix?\n\t\t} else {\n\t\t\texpectedRemote.IP = request.Address.IP()\n\t\t\texpectedRemote.Port = int(request.Port) // 0 is allowed\n\t\t}\n\t\ttempUDPConn = NewTempUDPConn(udpHub, writer, expectedRemote)\n\t}\n\tif err := writeSocks5Response(writer, statusSuccess, responseAddress, responsePort); err != nil {\n\t\tcommon.CloseIfExists(tempUDPConn)\n\t\treturn nil, nil, err\n\t}\n\n\treturn request, tempUDPConn, nil","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/proxy/socks/protocol.go#L190-L226","documentation":"Thrown in handshake5 (proxy/socks/protocol.go:208) when internet.ListenSystemPacket fails to bind the UDP socket for a UDP ASSOCIATE request. The server needs a local UDP listener (bound to the configured Address IP with port 0) to relay UDP; OS-level bind failure (permission, address unavailable, socket/port exhaustion, firewall) triggers this error.","triggerScenarios":"UDP ASSOCIATE arrives while the OS cannot allocate a UDP socket: UDP port range exhausted (many concurrent UDP sessions), the configured Address is not assigned to the host, UDP is blocked by seccomp/container policy, or the fd limit is reached.","commonSituations":"High-traffic relay nodes running out of ephemeral UDP ports or file descriptors; configs that pin an \"address\" IP that no longer exists on the interface; hardened containers denying socket(UDP); conntrack table exhaustion.","solutions":["Check the base error (address already in use / cannot assign requested address / permission denied) and fix that specific condition.","Raise limits: net.ipv4.ip_local_port_range, ulimit -n / LimitNOFILE, conntrack limits on the host.","If config.Address is set for the inbound, make sure that IP actually exists on a local interface, or remove it to use conn.LocalAddr().","Reduce concurrent UDP sessions or add relay capacity if the node is saturated."],"exampleFix":"# before: container/node defaults exhaust\nulimit -n 1024\n\n# after: room for UDP listeners\nulimit -n 65535\nsysctl -w net.ipv4.ip_local_port_range=\"10240 65535\"","handlingStrategy":"try-catch","validationCode":"// Pre-flight on the host: ensure a UDP socket can be bound before enabling UDP ASSOCIATE\nc, err := net.ListenPacket(\"udp\", \"127.0.0.1:0\")\nif err != nil {\n    return fmt.Errorf(\"UDP unavailable on host: %w\", err)\n}\nc.Close()","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to create UDP listener\") {\n    // log with base cause; alert if resource exhaustion (fd/port limits)\n    logError(\"UDP listener allocation failed: %v\", err)\n    return err\n}","preventionTips":["Raise RLIMIT_NOFILE and widen ip_local_port_range on relay hosts.","Ensure any configured inbound \"address\" IP exists on a local interface.","Monitor fd and conntrack usage to catch exhaustion before it becomes errors."],"tags":["socks","udp","socket","system-limits","config","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}