fatedier/frp · error

invalid visitor type: %s

Error message

invalid visitor type: %s

What it means

Returned by VisitorDefinition.Validate when the visitor's "type" string is not one of the three visitor-capable types: stcp, sudp, xtcp. Other proxy types (tcp, http, ...) cannot be visitors, and any typo or wrong casing fails here.

Source

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

	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
}

func (p *VisitorDefinition) ToConfigurer() (v1.VisitorConfigurer, error) {
	block, _, _ := p.activeBlock()
	if block == nil {

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Set "type" to exactly one of stcp, sudp, xtcp (lowercase).
2. Check for typos and stray whitespace in the type field.
3. Remember only p2p/secret types have visitors; for plain tcp/http proxies use a normal proxy, not a visitor.

Example fix

// before
{"name": "v", "type": "STCP", "stcp": {...}}

// after
{"name": "v", "type": "stcp", "stcp": {...}}

func isVisitorType(t string) bool {
    switch t {
    case "stcp", "sudp", "xtcp":
        return true
    }
    return false
}

When it happens

Trigger: POST/PUT /api/visitors with "type": "STCP", "type": "tcp", "type": "stc" (typo), or a missing/empty "type".

Common situations: Assuming every proxy type supports visitors; uppercase type strings; renaming after upgrades; copy-paste from a proxy definition into a visitor payload.

Related errors

• visitor name is required
• exactly one visitor type block is required
• visitor type block %q does not match type %q
• proxy name is required
• invalid proxy type: %s

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