{"record":{"id":"529391ad9d12615a","repo":"fatedier/frp","slug":"virtualnet-feature-is-not-enabled-enable-it-by-se","errorCode":null,"errorMessage":"VirtualNet feature is not enabled; enable it by setting the appropriate feature gate flag","messagePattern":"VirtualNet feature is not enabled; enable it by setting the appropriate feature gate flag","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/config/v1/validation/client.go","lineNumber":61,"sourceCode":"\t}\n\n\tfor _, validator := range validators {\n\t\tw, err := validator()\n\t\twarnings = AppendError(warnings, w)\n\t\terrs = AppendError(errs, err)\n\t}\n\treturn warnings, errs\n}\n\nfunc validateFeatureGates(c *v1.ClientCommonConfig) (Warning, error) {\n\tgates := featuregate.NewFeatureGate()\n\tif err := gates.SetFromMap(c.FeatureGates); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif c.VirtualNet.Address != \"\" {\n\t\tif !gates.Enabled(featuregate.VirtualNet) {\n\t\t\treturn nil, fmt.Errorf(\"VirtualNet feature is not enabled; enable it by setting the appropriate feature gate flag\")\n\t\t}\n\t}\n\treturn nil, nil\n}\n\n// ClientConfigRequirements describes runtime capabilities needed by a client configuration.\ntype ClientConfigRequirements struct {\n\tVirtualNet bool\n}\n\n// GetClientConfigRequirements returns the runtime capabilities needed by a client configuration.\nfunc GetClientConfigRequirements(\n\tcommon *v1.ClientCommonConfig,\n\tproxyCfgs []v1.ProxyConfigurer,\n\tvisitorCfgs []v1.VisitorConfigurer,\n) ClientConfigRequirements {\n\trequirements := ClientConfigRequirements{}\n\tif common != nil && common.VirtualNet.Address != \"\" {","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/pkg/config/v1/validation/client.go#L43-L79","documentation":"frp's client config validator rejects a configuration that sets virtualNet.address but does not enable the VirtualNet feature gate. Feature gates are an opt-in mechanism for experimental features, so the virtual network configuration is only honored when the gate 'VirtualNet' is explicitly set. The check runs during ValidateClientCommonConfig before the client starts.","triggerScenarios":"ClientCommonConfig has FeatureGates = nil or lacks key \"VirtualNet\", while c.VirtualNet.Address is non-empty. Happens when loading a TOML/YAML/JSON client config with a [virtualNet] section but no [featureGates] VirtualNet = true entry, or when gates.SetFromMap fails to see the key.","commonSituations":"Copying a virtualNet config block from docs or another machine without the featureGates block; upgrading frp where VirtualNet moved behind a gate; typos in the gate key (e.g. 'virtualnet' lowercase) so the gate map parses but never matches featuregate.VirtualNet.","solutions":["Add featureGates = { VirtualNet = true } (TOML: [featureGates]\\nVirtualNet = true) to the client config","Verify the gate key casing matches featuregate.VirtualNet exactly (case-sensitive)","If you do not need the virtual network, remove the [virtualNet] section (address field) from the config","Check frp release notes: VirtualNet is experimental and may require a build/version that includes it"],"exampleFix":"# before\n[featureGates]\n# (missing)\n\n[virtualNet]\naddress = \"10.26.0.1/16\"\n\n# after\n[featureGates]\nVirtualNet = true\n\n[virtualNet]\naddress = \"10.26.0.1/16\"","handlingStrategy":"validation","validationCode":"// Before starting frpc, validate the pair in Go:\nfunc hasVirtualNetGate(c *v1.ClientCommonConfig) bool {\n    gates := featuregate.NewFeatureGate()\n    if err := gates.SetFromMap(c.FeatureGates); err != nil {\n        return false\n    }\n    return gates.Enabled(featuregate.VirtualNet) || c.VirtualNet.Address == \"\"\n}","typeGuard":null,"tryCatchPattern":"if _, err := validation.ValidateClientCommonConfig(cfg); err != nil {\n    if strings.Contains(err.Error(), \"VirtualNet feature is not enabled\") {\n        // set FeatureGates[\"VirtualNet\"]=true or clear VirtualNet.Address, then retry validation\n    }\n    return err\n}","preventionTips":["Keep featureGates and the feature sections adjacent in config templates","Add a CI step running `frpc verify -c` on every config change","Document gate names case-sensitively"],"tags":["frp","config","feature-gate","virtual-network","go"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}