{"record":{"id":"75676628503a4386","repo":"XTLS/Xray-core","slug":"shadowsocks-settings-servers-should-have-one-an","errorCode":null,"errorMessage":"Shadowsocks settings: \"servers\" should have one and only one member. Multiple endpoints in \"servers\" should use multiple Shadowsocks outbounds and routing balancer instead","messagePattern":"Shadowsocks settings: \"servers\" should have one and only one member\\. Multiple endpoints in \"servers\" should use multiple Shadowsocks outbounds and routing balancer instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/shadowsocks.go","lineNumber":214,"sourceCode":"}\n\nfunc (v *ShadowsocksClientConfig) Build() (proto.Message, error) {\n\terrors.PrintNonRemovalDeprecatedFeatureWarning(\"Shadowsocks (with no Forward Secrecy, etc.)\", \"VLESS Encryption\")\n\n\tif v.Address != nil {\n\t\tv.Servers = []*ShadowsocksServerTarget{\n\t\t\t{\n\t\t\t\tAddress:  v.Address,\n\t\t\t\tPort:     v.Port,\n\t\t\t\tLevel:    v.Level,\n\t\t\t\tEmail:    v.Email,\n\t\t\t\tCipher:   v.Cipher,\n\t\t\t\tPassword: v.Password,\n\t\t\t},\n\t\t}\n\t}\n\tif len(v.Servers) != 1 {\n\t\treturn nil, errors.New(`Shadowsocks settings: \"servers\" should have one and only one member. Multiple endpoints in \"servers\" should use multiple Shadowsocks outbounds and routing balancer instead`)\n\t}\n\n\tif len(v.Servers) == 1 {\n\t\tserver := v.Servers[0]\n\t\tif C.Contains(shadowaead_2022.List, server.Cipher) {\n\t\t\tif server.Address == nil {\n\t\t\t\treturn nil, errors.New(\"Shadowsocks server address is not set.\")\n\t\t\t}\n\t\t\tif server.Port == 0 {\n\t\t\t\treturn nil, errors.New(\"Invalid Shadowsocks port.\")\n\t\t\t}\n\t\t\tif server.Password == \"\" {\n\t\t\t\treturn nil, errors.New(\"Shadowsocks password is not specified.\")\n\t\t\t}\n\n\t\t\tconfig := new(shadowsocks_2022.ClientConfig)\n\t\t\tconfig.Address = server.Address.Build()\n\t\t\tconfig.Port = uint32(server.Port)","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/shadowsocks.go#L196-L232","documentation":"The legacy Shadowsocks outbound 'servers' array must contain exactly one server entry; for load balancing you are expected to define multiple Shadowsocks outbounds plus a routing balancer. If 'servers' has zero or more than one element after the address shorthand normalization, this error is returned.","triggerScenarios":"A Shadowsocks outbound with a 'servers' array of length != 1, e.g. two endpoints for failover, or an empty array with no top-level address.","commonSituations":"Old V2Ray configs with multiple servers in one outbound; attempting load-balancing via multiple entries instead of balancers; providing neither 'address' shorthand nor 'servers'.","solutions":["Keep exactly one entry in 'servers' (or use the shorthand top-level address/port/password form).","For multiple endpoints, create one Shadowsocks outbound per endpoint and add a balancer group in routing rules.","Remove an empty 'servers' array and fill the top-level fields instead."],"exampleFix":"// before\n\"outbounds\": [{\n  \"protocol\": \"shadowsocks\",\n  \"settings\": {\"servers\": [srvA, srvB]}\n}]\n\n// after\n\"outbounds\": [\n  {\"tag\": \"ss-a\", \"protocol\": \"shadowsocks\", \"settings\": {\"servers\": [srvA]}},\n  {\"tag\": \"ss-b\", \"protocol\": \"shadowsocks\", \"settings\": {\"servers\": [srvB]}}\n],\n\"routing\": {\"balancers\": [{\"tag\": \"ss-bal\", \"selector\": [\"ss-a\", \"ss-b\"]}]}","handlingStrategy":"validation","validationCode":"func validSSOutbound(settings map[string]any) bool {\n    servers, ok := settings[\"servers\"].([]any)\n    return ok && len(servers) == 1\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Model multiple endpoints as multiple outbounds + balancer from the start"],"tags":["shadowsocks","outbound","balancer","config"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}