What causes "server name is required" in fatedier/frp?

Set serverName = " " — it must equal that proxy's name exactly, including case.

server name is required

Error message

server name is required

What it means

Validation error from validateVisitorBaseConfig: a visitor entry has an empty serverName. The serverName tells frpc which exported secret/p2p proxy (the server-side peer's proxy name) to connect to via frps; without it the visitor cannot identify its target. Second mandatory check in visitor base validation.

Source

Thrown at pkg/config/v1/validation/visitor.go:48

	switch v := c.(type) {
	case *v1.STCPVisitorConfig:
	case *v1.SUDPVisitorConfig:
	case *v1.XTCPVisitorConfig:
		return validateXTCPVisitorConfig(v)
	default:
		return errors.New("unknown visitor config type")
	}
	return nil
}

func validateVisitorBaseConfig(c *v1.VisitorBaseConfig) error {
	if c.Name == "" {
		return errors.New("name is required")
	}

	if c.ServerName == "" {
		return errors.New("server name is required")
	}

	if c.BindPort == 0 {
		return errors.New("bind port is required")
	}
	return nil
}

func validateXTCPVisitorConfig(c *v1.XTCPVisitorConfig) error {
	if !slices.Contains([]string{"kcp", "quic"}, c.Protocol) {
		return fmt.Errorf("protocol should be kcp or quic")
	}
	return nil
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Set serverName = "<name of the stcp/sudp/xtcp proxy on the server side>" — it must equal that proxy's name exactly, including case.
Do not put the frps address here; that belongs to serverAddr at the client top level.
Verify the matching proxy is actually running and reachable, and that secretKey matches it.

Example fix

# before
[[visitors]]
name = "v"
type = "stcp"
secretKey = "s"
bindAddr = "127.0.0.1"
bindPort = 9000

# after
[[visitors]]
name = "v"
type = "stcp"
serverName = "stcp-srv"
secretKey = "s"
bindAddr = "127.0.0.1"
bindPort = 9000

Defensive patterns

Strategy: validation

Validate before calling

base := v.GetBaseConfig()
if base == nil || base.ServerName == "" {
    return errors.New("visitor requires serverName equal to the server-side proxy name")
}

Type guard

func visitorTargetSet(c v1.VisitorConfigurer) bool {
    base := c.GetBaseConfig()
    return c != nil && base != nil && base.ServerName != ""
}

Try / catch

if err := validation.ValidateVisitorConfigurer(v); err != nil {
    if strings.Contains(err.Error(), "server name is required") {
        // set serverName to the stcp/sudp/xtcp proxy name on the other side
    }
    return err
}

Prevention

serverName is the peer proxy's name, not the frps address.
Keep the proxy name and its visitor serverName in one shared config doc.
Match secretKey on both sides at the same time.

When it happens

Trigger: A [[visitors]] entry missing serverName or with serverName = "". Common when the author confuses serverName (peer proxy name) with the frps server address (serverAddr) and omits it.

Common situations: First-time visitor configs assuming serverName is the frps host; copying the proxy's name field incorrectly; whitespace-only value after editing; programmatic construction skipping VisitorBaseConfig.ServerName.

Related errors

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