fatedier/frp · error

name is required

Error message

name is required

What it means

Validation error from validateVisitorBaseConfig: a [[visitors]] entry in the frpc config has an empty name. The visitor name identifies it locally in frpc (and pairs it with the client-side config), so it is mandatory. This is the first check in the visitor base validation, run by ValidateVisitorConfigurer for every visitor type.

Source

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

	base := c.GetBaseConfig()
	if err := validateVisitorBaseConfig(base); err != nil {
		return err
	}

	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

1. Add name = "my-visitor" to the [[visitors]] entry.
2. Keep the name distinct from serverName: name identifies the local visitor, serverName identifies the remote proxy being visited.
3. If generating configs in Go, set VisitorBaseConfig.Name before validation.

Example fix

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

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

for _, v := range clientCfg.Visitors {
    if v.GetBaseConfig() == nil || v.GetBaseConfig().Name == "" {
        return errors.New("every visitor needs a non-empty name")
    }
}

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

if err := validation.ValidateVisitorConfigurer(v); err != nil {
    if strings.Contains(err.Error(), "name is required") {
        // add name = "my-visitor" to the [[visitors]] entry
    }
    return err
}

When it happens

Trigger: A [[visitors]] entry whose name key is missing or set to "" — e.g. a copied visitor template where name was deleted, or TOML keys misplaced so the entry decodes to zero values.

Common situations: Writing the first stcp/xtcp visitor and forgetting that visitors need their own name distinct from serverName; key typo like Name or visitor; programmatic visitor construction without VisitorBaseConfig.Name.

Related errors

• name should not be empty
• server name is required
• bind port is required
• type shouldn't be empty
• type [%s] error

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