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 public IP or lan IP or other, we can not decide for you

What it means

Like error 40 but for a different socks5 server path: the socks5 listener needs a concrete host IP so UDP relay replies know where to originate/advertise. When net.SplitHostPort yields an empty host and --socks5ServerIP is also empty, brook throws this error, asking for a public or LAN IP it cannot infer.

Source

Thrown at cli/brook/main.go:2349

				&cli.BoolFlag{
					Name:  "example",
					Usage: "Show a minimal example of usage",
				},
			},
			Action: func(c *cli.Context) error {
				if c.Bool("example") {
					fmt.Println("brook socks5 --listen :9999 --socks5ServerIP 1.2.3.4")
					return nil
				}
				if c.String("listen") == "" {
					return cli.ShowSubcommandHelp(c)
				}
				h, _, err := net.SplitHostPort(c.String("listen"))
				if err != nil {
					return err
				}
				if h == "" && c.String("socks5ServerIP") == "" {
					return errors.New("socks5 server requires a clear IP for UDP, only port is not enough. You may use public IP or lan IP or other, we can not decide for you")
				}
				var ip string
				if h != "" {
					ip = h
				}
				if c.String("socks5ServerIP") != "" {
					ip = c.String("socks5ServerIP")
				}
				s, err := brook.NewSocks5Server(c.String("listen"), ip, c.String("username"), c.String("password"), c.Int("tcpTimeout"), c.Int("udpTimeout"))
				if err != nil {
					return err
				}
				s.Server.LimitUDP = c.Bool("limitUDP")
				g.Add(&runnergroup.Runner{
					Start: func() error {
						return s.ListenAndServe()
					},
					Stop: func() error {

View on GitHub (pinned to 5cd13ef3b1)

Solutions

1. Bind with an explicit host: `-l 0.0.0.0:1080` or your LAN/public IP
2. Supply --socks5ServerIP with the address UDP clients should use (e.g. the machine's public IP)
3. Document the intended IP in your deployment template so the flag is never omitted

Example fix

// before
brook socks5 -l :1080
// after
brook socks5 -l :1080 --socks5ServerIP 203.0.113.10

When it happens

Trigger: Running the socks5 server subcommand with a port-only listen value such as `-l :1080` and no --socks5ServerIP, hitting the check at cli/brook/main.go:2349.

Common situations: Container deployments where users bind on all interfaces with `:port`; scripts that only parameterize the port; users assuming brook will auto-detect the public IP (it deliberately will not).

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• socks5 server requires a clear IP for UDP, only port is not
• Looks like you want create socks5 from a socks5, you may wan
• invalid packet. length: ${len} address: ${a} ${h} ${p}
• quic max datagram size is 1197
• when write to client, quic max datagram size is 1197

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