{"record":{"id":"ce186bfaa6654976","repo":"fatedier/frp","slug":"subdomain-is-not-supported-because-this-feature-is","errorCode":null,"errorMessage":"subdomain is not supported because this feature is not enabled in server","messagePattern":"subdomain is not supported because this feature is not enabled in server","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/config/v1/validation/proxy.go","lineNumber":94,"sourceCode":"\t\treturn errors.New(\"subdomain and custom domains should not be both empty\")\n\t}\n\treturn nil\n}\n\nfunc validateDomainConfigForServer(c *v1.DomainConfig, s *v1.ServerConfig) error {\n\tsubDomainHost := strings.ToLower(s.SubDomainHost)\n\tfor _, domain := range c.CustomDomains {\n\t\tcanonicalDomain := strings.ToLower(domain)\n\t\tif subDomainHost != \"\" && len(strings.Split(subDomainHost, \".\")) < len(strings.Split(canonicalDomain, \".\")) {\n\t\t\tif strings.HasSuffix(canonicalDomain, \".\"+subDomainHost) {\n\t\t\t\treturn fmt.Errorf(\"custom domain [%s] should not belong to subdomain host [%s]\", domain, s.SubDomainHost)\n\t\t\t}\n\t\t}\n\t}\n\n\tif c.SubDomain != \"\" {\n\t\tif s.SubDomainHost == \"\" {\n\t\t\treturn errors.New(\"subdomain is not supported because this feature is not enabled in server\")\n\t\t}\n\n\t\tif strings.Contains(c.SubDomain, \".\") || strings.Contains(c.SubDomain, \"*\") {\n\t\t\treturn errors.New(\"'.' and '*' are not supported in subdomain\")\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc ValidateProxyConfigurerForClient(c v1.ProxyConfigurer) error {\n\tbase := c.GetBaseConfig()\n\tif err := validateProxyBaseConfigForClient(base); err != nil {\n\t\treturn err\n\t}\n\n\tswitch v := c.(type) {\n\tcase *v1.TCPProxyConfig:\n\t\treturn validateTCPProxyConfigForClient(v)","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/pkg/config/v1/validation/proxy.go#L76-L112","documentation":"Server-side validation error from validateDomainConfigForServer: an incoming proxy declares subdomain = \"...\" but the frps server has no subDomainHost configured. Client-declared subdomains are expanded as <subdomain>.<subDomainHost>, which is impossible without a host; frps therefore rejects the proxy registration. This runs when frps validates proxies against its own ServerConfig.","triggerScenarios":"frps config has no subDomainHost set (or it is an empty string) while an frpc http/https/tcpmux proxy registers with subdomain set; the new proxy fails validation and is rejected at registration time.","commonSituations":"Client and server configs drift: the client config was written for a server with subdomain routing enabled, but points at (or was updated to) a server without subDomainHost; new frps deployments where the operator forgot to set subDomainHost; typos like subdomainHost vs subdomainHost casing in TOML leaving it unset.","solutions":["On the frps side, set subDomainHost = \"frps.example.com\" in the server config and restart frps.","On the client side, replace subdomain with customDomains = [\"web.frps.example.com\"] and add DNS records pointing at frps.","If subdomain routing is not wanted, remove subdomain from the client proxy entirely (but http-type proxies then need customDomains)."],"exampleFix":"# before (frps.toml)\nbindPort = 7000\n# no subDomainHost\n\n# after (frps.toml)\nbindPort = 7000\nsubDomainHost = \"frps.example.com\"","handlingStrategy":"validation","validationCode":"// frps side, before serving\nif serverCfg.SubDomainHost == \"\" {\n    // reject/disable subdomain expectations: log or fail fast\n    log.Warn(\"subDomainHost not set; client proxies using subdomain will be rejected\")\n}","typeGuard":"func subdomainAllowed(s *v1.ServerConfig) bool {\n    return s != nil && s.SubDomainHost != \"\"\n}","tryCatchPattern":"if err := validation.ValidateProxyConfigurerForServer(p, serverCfg); err != nil {\n    if strings.Contains(err.Error(), \"subdomain is not supported because this feature is not enabled in server\") {\n        // set subDomainHost on frps or switch the client to customDomains\n    }\n    return err\n}","preventionTips":["Document the frps subDomainHost wherever client configs are generated.","Prefer customDomains with explicit DNS when server config is not under your control.","Sync server config changes (subDomainHost) with all client configs that use subdomain."],"tags":["config","proxy","subdomain","validation","frps","routing"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}