txthinking/brook · error

socks5 server requires a clear IP for UDP, only port is not

Error message

socks5 server requires a clear IP for UDP, only port is not enough. You may use loopback IP or lan IP or other, we can not decide for you

What it means

The socks5 subcommand needs a concrete IP address (not just a port) to bind/advertise its UDP relay. After applying the --socks5ServerIP override, if the host portion h is still empty the command aborts, because a port-only address cannot host a socks5 UDP ASSOC. The message suggests choosing loopback, LAN, or another IP explicitly.

Source

Thrown at cli/brook/main.go:480

				}
				var link = ""
				if c.String("server") != "" {
					v := url.Values{}
					v.Set("password", c.String("password"))
					link = brook.Link("server", c.String("server"), v)
				}
				if c.String("link") != "" {
					link = c.String("link")
				}
				h, p, err := net.SplitHostPort(c.String("socks5"))
				if err != nil {
					return err
				}
				if c.String("socks5ServerIP") != "" {
					h = c.String("socks5ServerIP")
				}
				if h == "" {
					return errors.New("socks5 server requires a clear IP for UDP, only port is not enough. You may use loopback IP or lan IP or other, we can not decide for you")
				}
				kind, _, v, err := brook.ParseLink(link)
				if err != nil {
					return err
				}
				if s := v.Get("clientHKDFInfo"); s != "" {
					brook.ClientHKDFInfo = []byte(s)
				}
				if s := v.Get("serverHKDFInfo"); s != "" {
					brook.ServerHKDFInfo = []byte(s)
				}
				if kind == "socks5" {
					return errors.New("Looks like you want create socks5 from a socks5, you may want $ brook socks5tohttp?")
				}
				s, err := brook.NewBrookLink(link)
				if err != nil {
					return err
				}

View on GitHub (pinned to 5cd13ef3b1)

Solutions

1. Set --socks5ServerIP to an explicit IP, e.g. --socks5ServerIP 127.0.0.1 or your LAN IP
2. Or specify the full listen address with host: --socks5 127.0.0.1:1080
3. Use 0.0.0.0 if you truly want all interfaces — any concrete IP is accepted, only empty is rejected

Example fix

// before
brook socks5 --socks5 :1080 --password x
// after
brook socks5 --socks5 127.0.0.1:1080 --socks5ServerIP 127.0.0.1 --password x

# before running, ensure a host is present
[[ "$socks5_addr" == *:*"" ]] && host="${socks5_addr%%:*}" || host="$socks5ServerIP"
[ -n "$host" ] || { echo "socks5 server needs an explicit IP for UDP; set --socks5ServerIP" >&2; exit 1; }

When it happens

Trigger: Running `brook socks5 --socks5 :1080` (or a value without a host) without --socks5ServerIP, so h derived from --socks5 remains empty after the `c.String("socks5ServerIP")` override at cli/brook/main.go:480.

Common situations: Users accustomed to port-only listening for TCP assume :1080 suffices; container setups where the LAN IP is unknown; configs copied from TCP-only examples.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Looks like you want create socks5 from a socks5, you may wan
• --cert must be with absolute path
• --certkey must be with absolute path
• socks5 server requires a clear IP for UDP, only port is not
• invalid packet. length: ${len} address: ${a} ${h} ${p}

AI-assisted analysis of txthinking/brook@5cd13ef3b1 (2026-09-06). Data as JSON: /api/errors/59252c97567c700e. Report an issue: GitHub.