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

Add a non-empty top-level "name" to the visitor definition body.

visitor name is required

Error message

visitor name is required

What it means

Returned by VisitorDefinition.Validate when creating/updating a visitor through frpc's admin API and the JSON body's "name" is empty or whitespace-only. Visitors (stcp/sudp/xtcp clients connecting to a peer) are identified by name, so the request is rejected immediately.

Source

Thrown at client/http/model/visitor_definition.go:21

import (
	"fmt"
	"strings"

	v1 "github.com/fatedier/frp/pkg/config/v1"
)

type VisitorDefinition struct {
	Name string `json:"name"`
	Type string `json:"type"`

	STCP *v1.STCPVisitorConfig `json:"stcp,omitempty"`
	SUDP *v1.SUDPVisitorConfig `json:"sudp,omitempty"`
	XTCP *v1.XTCPVisitorConfig `json:"xtcp,omitempty"`
}

func (p *VisitorDefinition) Validate(pathName string, isUpdate bool) error {
	if strings.TrimSpace(p.Name) == "" {
		return fmt.Errorf("visitor name is required")
	}
	if !IsVisitorType(p.Type) {
		return fmt.Errorf("invalid visitor type: %s", p.Type)
	}
	if isUpdate && pathName != "" && pathName != p.Name {
		return fmt.Errorf("visitor name in URL must match name in body")
	}

	_, blockType, blockCount := p.activeBlock()
	if blockCount != 1 {
		return fmt.Errorf("exactly one visitor type block is required")
	}
	if blockType != p.Type {
		return fmt.Errorf("visitor type block %q does not match type %q", blockType, p.Type)
	}
	return nil
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Add a non-empty top-level "name" to the visitor definition body.
Ensure the name is unique among this client's visitors.
Trim and assert the name client-side before sending.

Example fix

// before
{"type": "stcp", "stcp": {"serverName": "secret", "secretKey": "k"}}

// after
{"name": "secret-visitor", "type": "stcp", "stcp": {"serverName": "secret", "secretKey": "k"}}

Defensive patterns

Strategy: validation

Validate before calling

func validVisitorName(def map[string]any) error {
    name, _ := def["name"].(string)
    if strings.TrimSpace(name) == "" { return errors.New("visitor name is required") }
    return nil
}

Try / catch

if resp.StatusCode == 400 && strings.Contains(body, "visitor name is required") {
    // regenerate payload with name set and retry once
}

Prevention

Always emit the top-level name for visitor payloads.
Keep visitor names distinct per client.
Validate payload shape in client SDK code before calling the API.

When it happens

Trigger: POST/PUT /api/visitors with {"type":"stcp","stcp":{...}} and no top-level "name" key, or "name": " ".

Common situations: Client generator omitting the name field; name nested inside the stcp/sudp/xtcp block instead of the top level; whitespace-only name from templating.

Related errors

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