fatedier/frp · error
unixPath is required
Error message
unixPath is required
What it means
Validation error from validateUnixDomainSocketPluginOptions: the unix_domain_socket plugin is configured but UnixPath is empty. The plugin proxies frps traffic to a local Unix domain socket, so the socket file path is mandatory. Enforced during client-side proxy config validation.
Source
Thrown at pkg/config/v1/validation/plugin.go:71
}
func validateHTTPS2HTTPSPluginOptions(c *v1.HTTPS2HTTPSPluginOptions) error {
if c.LocalAddr == "" {
return errors.New("localAddr is required")
}
return nil
}
func validateStaticFilePluginOptions(c *v1.StaticFilePluginOptions) error {
if c.LocalPath == "" {
return errors.New("localPath is required")
}
return nil
}
func validateUnixDomainSocketPluginOptions(c *v1.UnixDomainSocketPluginOptions) error {
if c.UnixPath == "" {
return errors.New("unixPath is required")
}
return nil
}
func validateTLS2RawPluginOptions(c *v1.TLS2RawPluginOptions) error {
if c.LocalAddr == "" {
return errors.New("localAddr is required")
}
return nil
}
View on GitHub (pinned to 6c8a8d0a97)
Solutions
- Add unixPath = "/var/run/docker.sock" (path to the local Unix socket) in the plugin options.
- Ensure the frpc process user has read/write permission on the socket file.
- Use the exact key unixPath — not localAddr, which belongs to other plugins.
Example fix
# before [[proxies]] name = "docker" type = "tcp" remotePort = 6000 [proxies.plugin] type = "unix_domain_socket" # after [[proxies]] name = "docker" type = "tcp" remotePort = 6000 [proxies.plugin] type = "unix_domain_socket" unixPath = "/var/run/docker.sock"
Defensive patterns
Strategy: validation
Validate before calling
if pluginType == "unix_domain_socket" && pluginOpts.UnixPath == "" {
return errors.New("unix_domain_socket plugin requires unixPath")
} Type guard
func udsPluginComplete(o *v1.UnixDomainSocketPluginOptions) bool {
return o != nil && o.UnixPath != ""
} Try / catch
if err := validation.ValidateProxyConfigurerForClient(cfg); err != nil {
if strings.Contains(err.Error(), "unixPath is required") {
// add unixPath = "/var/run/docker.sock" to the plugin options
}
return err
} Prevention
- Remember the key is unixPath — not localAddr or path.
- Check the socket file exists and permissions allow the frpc user.
- Guard docker.sock exposure with auth on the frps side.
When it happens
Trigger: A proxy with plugin = "unix_domain_socket" whose plugin options lack unixPath — e.g. the plugin block exists but no path key, or the key was written as localAddr/path instead of unixPath.
Common situations: Exposing a Docker daemon socket, a database over UDS, or CRI runtime sockets without specifying the socket file; carrying over a TCP plugin template and leaving the wrong address field; typos like unixpath or unix_path.
Related errors
- localAddr is required
- localPath is required
- plugin type is empty
- visitor plugin type is empty
- name should not be empty
AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15).
Data as JSON: /api/errors/a13dbe93d1b0e218.
Report an issue: GitHub.