What causes "unknown proxy config type" in fatedier/frp?

unknown proxy config type

Error message

unknown proxy config type

What it means

Error from ValidateProxyConfigurerForClient: the provided ProxyConfigurer is not one of the known client proxy types (TCP, UDP, TCPMux, HTTP, HTTPS, STCP, XTCP, SUDP). The function switches on the concrete Go type of the configurer; an unregistered or nil-typed configurer falls through to this default. Typically indicates a version mismatch where a newer client config type was constructed but this validation build does not know it, or a custom ProxyConfigurer implementation was passed.

Source

Thrown at pkg/config/v1/validation/proxy.go:128

	switch v := c.(type) {
	case *v1.TCPProxyConfig:
		return validateTCPProxyConfigForClient(v)
	case *v1.UDPProxyConfig:
		return validateUDPProxyConfigForClient(v)
	case *v1.TCPMuxProxyConfig:
		return validateTCPMuxProxyConfigForClient(v)
	case *v1.HTTPProxyConfig:
		return validateHTTPProxyConfigForClient(v)
	case *v1.HTTPSProxyConfig:
		return validateHTTPSProxyConfigForClient(v)
	case *v1.STCPProxyConfig:
		return validateSTCPProxyConfigForClient(v)
	case *v1.XTCPProxyConfig:
		return validateXTCPProxyConfigForClient(v)
	case *v1.SUDPProxyConfig:
		return validateSUDPProxyConfigForClient(v)
	}
	return errors.New("unknown proxy config type")
}

func validateTCPProxyConfigForClient(c *v1.TCPProxyConfig) error {
	return nil
}

func validateUDPProxyConfigForClient(c *v1.UDPProxyConfig) error {
	return nil
}

func validateTCPMuxProxyConfigForClient(c *v1.TCPMuxProxyConfig) error {
	if err := validateDomainConfigForClient(&c.DomainConfig); err != nil {
		return err
	}

	if !slices.Contains([]string{string(v1.TCPMultiplexerHTTPConnect)}, c.Multiplexer) {
		return fmt.Errorf("not support multiplexer: %s", c.Multiplexer)
	}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Use one of the built-in configurers: *v1.TCPProxyConfig, *v1.UDPProxyConfig, *v1.TCPMuxProxyConfig, *v1.HTTPProxyConfig, *v1.HTTPSProxyConfig, *v1.STCPProxyConfig, *v1.XTCPProxyConfig, *v1.SUDPProxyConfig.
If embedding frp, keep library version in sync with the config types you construct (no custom proxy types are supported).
Check for a nil configurer before calling validation.

Example fix

// before
var cfg v1.ProxyConfigurer // nil interface
err := validation.ValidateProxyConfigurerForClient(cfg)

// after
cfg := &v1.TCPProxyConfig{
    ProxyBaseConfig: &v1.ProxyBaseConfig{Name: "ssh"},
    RemotePort: 22,
}
err := validation.ValidateProxyConfigurerForClient(cfg)

Defensive patterns

Strategy: type-guard

Validate before calling

func isKnownClientProxyType(c v1.ProxyConfigurer) bool {
    switch c.(type) {
    case *v1.TCPProxyConfig, *v1.UDPProxyConfig, *v1.TCPMuxProxyConfig,
        *v1.HTTPProxyConfig, *v1.HTTPSProxyConfig, *v1.STCPProxyConfig,
        *v1.XTCPProxyConfig, *v1.SUDPProxyConfig:
        return true
    }
    return false
}

Type guard

func isKnownClientProxyType(c v1.ProxyConfigurer) bool {
    switch c.(type) {
    case *v1.TCPProxyConfig, *v1.UDPProxyConfig, *v1.TCPMuxProxyConfig,
        *v1.HTTPProxyConfig, *v1.HTTPSProxyConfig, *v1.STCPProxyConfig,
        *v1.XTCPProxyConfig, *v1.SUDPProxyConfig:
        return true
    default:
        return false
    }
}

Try / catch

if !isKnownClientProxyType(cfg) {
    return fmt.Errorf("unsupported proxy configurer %T", cfg)
}
if err := validation.ValidateProxyConfigurerForClient(cfg); err != nil { return err }

Prevention

Never pass custom or nil ProxyConfigurer implementations into frp validation.
Pin frp library versions so constructed config types match the validator.
Unit-test config generation against the validation package.

When it happens

Trigger: Programmatically calling validation.ValidateProxyConfigurerForClient(c) with a ProxyConfigurer that is nil, a custom struct implementing the interface, or a type introduced after this build; config-file paths normally cannot produce it because the decoder rejects unknown proxy types earlier at JSON decode time.

Common situations: Embedding frp as a library and defining a custom proxy type; mixed-version binaries (config decoded by a newer frp, validated by an older one); passing a typed nil pointer (*v1.TCPProxyConfig)(nil) which still matches the type switch but is unusual; plain nil interface hitting the default branch.

Related errors

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