fatedier/frp · error

listen udp port %s error: %v

Error message

listen udp port %s error: %v

What it means

Thrown by SUDPVisitor.Run when net.ListenUDP fails to bind the resolved address for the sudp visitor — the address parsed fine, but the OS refused the UDP bind. The message includes the offending address string and the OS error (e.g. 'address already in use' or 'permission denied').

Source

Thrown at client/visitor/sudp.go:56

	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
}

func (sv *SUDPVisitor) dispatcher() {
	xl := xlog.FromContextSafe(sv.ctx)

	var (
		visitorConn net.Conn

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Pick a free bindPort: check with ss -uln / lsof -i udp:PORT.
2. If using a privileged port, run frpc with CAP_NET_BIND_SERVICE or switch to a port >=1024.
3. Make sure bindAddr exists on the host (or use 127.0.0.1/0.0.0.0).
4. Deduplicate port assignments across visitors and local services.

Example fix

# before — port 53 already in use / privileged
[visitors.sudp]
bindAddr = "0.0.0.0"
bindPort = 53

# after
[visitors.sudp]
bindAddr = "0.0.0.0"
bindPort = 5353

// Check the UDP port is free before starting frpc with a sudp visitor
addr, _ := net.ResolveUDPAddr("udp", net.JoinHostPort(bindAddr, strconv.Itoa(bindPort)))
if c, err := net.ListenUDP("udp", addr); err != nil {
    return fmt.Errorf("bindPort %d not available: %w", bindPort, err)
} else { c.Close() }

if err := visitor.Run(); err != nil {
    if strings.Contains(err.Error(), "listen udp port") {
        // pick another bindPort or stop the conflicting process, then recreate visitor
    }
}

When it happens

Trigger: bindPort already bound by another process (another frpc visitor, a local service); binding a privileged port (<1024) as non-root; bindAddr being an IP not present on the machine; or ephemeral-port exhaustion in containers.

Common situations: Two visitors (or a local app and the visitor) configured with the same bindPort; running frpc unprivileged while bindPort < 1024; container missing the interface the config names.

Related errors

• sudp ResolveUDPAddr error: %v
• ErrNoTunnelSession
• visitor plugin type is empty
• unknown visitor config type
• name is required

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