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

Add a non-empty "name" at the top level of the proxy definition JSON body.

proxy name is required

Error message

proxy name is required

What it means

Returned by ProxyDefinition.Validate when creating/updating a proxy through frpc's admin API (POST/PUT /api/proxies) and the JSON body's "name" field is empty or whitespace-only. The name is the primary identifier of a proxy, so the request is rejected before any type/block validation runs.

Source

Thrown at client/http/model/proxy_definition.go:26

)

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

	TCP    *v1.TCPProxyConfig    `json:"tcp,omitempty"`
	UDP    *v1.UDPProxyConfig    `json:"udp,omitempty"`
	HTTP   *v1.HTTPProxyConfig   `json:"http,omitempty"`
	HTTPS  *v1.HTTPSProxyConfig  `json:"https,omitempty"`
	TCPMux *v1.TCPMuxProxyConfig `json:"tcpmux,omitempty"`
	STCP   *v1.STCPProxyConfig   `json:"stcp,omitempty"`
	SUDP   *v1.SUDPProxyConfig   `json:"sudp,omitempty"`
	XTCP   *v1.XTCPProxyConfig   `json:"xtcp,omitempty"`
}

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

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

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Add a non-empty "name" at the top level of the proxy definition JSON body.
Trim/verify the name client-side before sending (it must not be only whitespace).
Ensure the name is unique among the client's proxies to avoid later conflicts.

Example fix

// before
body := {"type": "tcp", "tcp": {"localPort": 22}}

// after
body := {"name": "ssh", "type": "tcp", "tcp": {"localPort": 22}}

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

resp, err := http.Post(apiURL+"/api/proxies", "application/json", body)
if err != nil { return err }
if resp.StatusCode == 400 {
    // read body; if "proxy name is required", fix payload and retry with name set
}

Prevention

Always set the top-level name field when building proxy definitions programmatically.
Keep names unique and DNS-safe to avoid downstream conflicts.
Run definitions through a local Validate-equivalent before POSTing.

When it happens

Trigger: Calling the frpc HTTP API with a proxy definition whose top-level "name" is "" or missing, e.g. {"type":"tcp","tcp":{...}} with no "name" key, or "name": " ".

Common situations: Client code that builds the JSON dynamically and forgets to set name; YAML/TOML-to-JSON conversion dropping the field; name accidentally placed inside the type block instead of at the top level.

Related errors

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