fatedier/frp · error

plugin [%s] is not registered

Error message

plugin [%s] is not registered

What it means

Visitor-side plugin factory lookup failed: Create() found no CreatorFn registered under the requested name in the visitor plugin registry. This registry is separate from the client proxy-plugin registry and currently holds few entries (e.g. virtual_net), so most names are simply not visitor plugins.

Source

Thrown at pkg/plugin/visitor/plugin.go:58

}

// Creators is used for create plugins to handle connections.
var creators = make(map[string]CreatorFn)

type CreatorFn func(pluginCtx PluginContext, options v1.VisitorPluginOptions) (Plugin, error)

func Register(name string, fn CreatorFn) {
	if _, exist := creators[name]; exist {
		panic(fmt.Sprintf("plugin [%s] is already registered", name))
	}
	creators[name] = fn
}

func Create(pluginName string, pluginCtx PluginContext, options v1.VisitorPluginOptions) (p Plugin, err error) {
	if fn, ok := creators[pluginName]; ok {
		p, err = fn(pluginCtx, options)
	} else {
		err = fmt.Errorf("plugin [%s] is not registered", pluginName)
	}
	return
}

type Plugin interface {
	Name() string
	Start()
	Close() error
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Use a valid visitor plugin type for your frp version (e.g. virtual_net for virtual network visitors)
2. Fix typos in [visitors.plugin].type
3. Upgrade frpc if the visitor plugin you need shipped in a later release

Example fix

// before
[[visitors]]
name = "vn"
type = "stty"
[visitors.plugin]
type = "virtualnet"

// after
type = "stty"
[visitors.plugin]
type = "virtual_net"

visitorPlugins := map[string]bool{"virtual_net": true}
if !visitorPlugins[cfg.Visitor.Plugin.Type] {
    return fmt.Errorf("unknown visitor plugin %q", cfg.Visitor.Plugin.Type)
}

if _, err := visitorplugin.Create(name, vCtx, opts); err != nil {
    if strings.Contains(err.Error(), "is not registered") {
        return fmt.Errorf("config error: %w (check visitor plugin type)", err)
    }
    return err
}

When it happens

Trigger: A visitor config whose [visitors.plugin].type does not match a registered visitor plugin name — typo, or trying to use a proxy-side plugin name in a visitor block.

Common situations: Config copy-paste putting an http/socks5 proxy plugin type into a visitor section; misspelled "virtual_net"; plugin exists only in newer frp versions.

Related errors

• plugin [%s] is not registered
• invalid destination IP address [%s]
• unmarshal visitor plugin error: %v
• unknown visitor plugin type: %s
• unmarshal VisitorPluginOptions error: %v

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