fatedier/frp · error

sudp ResolveUDPAddr error: %v

Error message

sudp ResolveUDPAddr error: %v

What it means

Thrown by SUDPVisitor.Run when net.ResolveUDPAddr fails to parse the bind address for the secret UDP visitor — i.e. the combination of cfg.BindAddr and cfg.BindPort is not a valid UDP address. This is a pure configuration error; no socket is opened yet.

Source

Thrown at client/visitor/sudp.go:51

type SUDPVisitor struct {
	*BaseVisitor

	checkCloseCh chan struct{}
	// udpConn is the listener of udp packet
	udpConn *net.UDPConn
	readCh  chan *msg.UDPPacket
	sendCh  chan *msg.UDPPacket

	cfg *v1.SUDPVisitorConfig
}

// SUDP Run start listen a udp port
func (sv *SUDPVisitor) Run() (err error) {
	xl := xlog.FromContextSafe(sv.ctx)

	addr, err := net.ResolveUDPAddr("udp", net.JoinHostPort(sv.cfg.BindAddr, strconv.Itoa(sv.cfg.BindPort)))
	if err != nil {
		return fmt.Errorf("sudp ResolveUDPAddr error: %v", err)
	}

	sv.udpConn, err = net.ListenUDP("udp", addr)
	if err != nil {
		return fmt.Errorf("listen udp port %s error: %v", addr.String(), err)
	}

	sv.sendCh = make(chan *msg.UDPPacket, 1024)
	sv.readCh = make(chan *msg.UDPPacket, 1024)

	xl.Infof("sudp start to work, listen on %s", addr)

	go sv.dispatcher()
	go udp.ForwardUserConn(sv.udpConn, sv.readCh, sv.sendCh, int(sv.clientCfg.UDPPacketSize))

	return
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Set bindAddr to a valid IP or hostname (use "127.0.0.1" for local-only, "0.0.0.0" for all interfaces).
2. Ensure bindPort is an integer in 0-65535.
3. Wrap IPv6 literals in brackets when combined with a port, or rely on the separate bindPort field.
4. Validate the address with net.ResolveUDPAddr in your config tooling before deploying.

Example fix

# before (frpc.toml)
[[visitors]]
name = "v"
type = "sudp"
[visitors.sudp]
bindAddr = "my host"
bindPort = 70000

# after
[visitors.sudp]
bindAddr = "127.0.0.1"
bindPort = 6000

// Pre-validate the visitor bind address exactly as Run() will build it
if _, err := net.ResolveUDPAddr("udp", net.JoinHostPort(bindAddr, strconv.Itoa(bindPort))); err != nil {
    return fmt.Errorf("invalid sudp visitor bind address: %w", err)
}

When it happens

Trigger: A sudp visitor with bindAddr set to an invalid host string (unresolvable name at parse time like "my host", malformed IPv6, empty-with-bad-port) or bindPort outside 0-65535 (e.g. a negative number or >65535 from templating).

Common situations: Templated configs injecting an unset variable producing garbage; IPv6 literal missing brackets; port computed dynamically overflowing 65535; copy-paste errors in bindAddr.

Related errors

• listen udp port %s error: %v
• visitor plugin type is empty
• name is required
• server name is required
• bind port is required

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/76206e10567236d4. Report an issue: GitHub.