{"record":{"id":"86c1f9f81436c8a4","repo":"XTLS/Xray-core","slug":"vless-settings-vnext-should-have-one-and-only-o","errorCode":null,"errorMessage":"VLESS settings: \"vnext\" should have one and only one member. Multiple endpoints in \"vnext\" should use multiple VLESS outbounds and routing balancer instead","messagePattern":"VLESS settings: \"vnext\" should have one and only one member\\. Multiple endpoints in \"vnext\" should use multiple VLESS outbounds and routing balancer instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/vless.go","lineNumber":273,"sourceCode":"\tTestpre    uint32                `json:\"testpre\"`\n\tTestseed   []uint32              `json:\"testseed\"`\n\tVnext      []*VLessOutboundVnext `json:\"vnext\"`\n}\n\n// Build implements Buildable\nfunc (c *VLessOutboundConfig) Build() (proto.Message, error) {\n\tconfig := new(outbound.Config)\n\tif c.Address != nil {\n\t\tc.Vnext = []*VLessOutboundVnext{\n\t\t\t{\n\t\t\t\tAddress: c.Address,\n\t\t\t\tPort:    c.Port,\n\t\t\t\tUsers:   []json.RawMessage{{}},\n\t\t\t},\n\t\t}\n\t}\n\tif len(c.Vnext) != 1 {\n\t\treturn nil, errors.New(`VLESS settings: \"vnext\" should have one and only one member. Multiple endpoints in \"vnext\" should use multiple VLESS outbounds and routing balancer instead`)\n\t}\n\tfor _, rec := range c.Vnext {\n\t\tif rec.Address == nil {\n\t\t\treturn nil, errors.New(`VLESS vnext: \"address\" is not set`)\n\t\t}\n\t\tif len(rec.Users) != 1 {\n\t\t\treturn nil, errors.New(`VLESS vnext: \"users\" should have one and only one member. Multiple members in \"users\" should use multiple VLESS outbounds and routing balancer instead`)\n\t\t}\n\t\tspec := &protocol.ServerEndpoint{\n\t\t\tAddress: rec.Address.Build(),\n\t\t\tPort:    uint32(rec.Port),\n\t\t}\n\t\tfor _, rawUser := range rec.Users {\n\t\t\tuser := new(protocol.User)\n\t\t\tif c.Address != nil {\n\t\t\t\tuser.Level = c.Level\n\t\t\t\tuser.Email = c.Email\n\t\t\t} else {","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/vless.go#L255-L291","documentation":"Thrown by VLessOutboundConfig.Build() when the \"vnext\" array of a full-style VLESS outbound does not contain exactly one endpoint. Xray requires one server per outbound; load balancing across multiple VLESS servers must be expressed as multiple outbounds plus a routing balancer. Note: if the simplified style is used (top-level \"address\"), the builder synthesizes a single vnext automatically, so this error only fires in full style with 0 or 2+ vnext entries.","triggerScenarios":"Full-style outbound with \"vnext\": [] or with two server objects; also a config that sets neither top-level address nor vnext (len 0).","commonSituations":"Users migrating from V2Ray 3.x-style configs that allowed multiple vnext entries for failover; aggregating several servers into one outbound 'to save space'; forgetting vnext entirely when streamSettings were filled in.","solutions":["Keep exactly one object in \"vnext\" per outbound","For multiple servers: create one VLESS outbound per server and route through a balancer (\"routing\":{\"balancers\":[...]})","Or switch to the simplified style: put \"address\", \"port\", \"id\" at the outbound top level and drop \"vnext\" entirely"],"exampleFix":"// before (one outbound, two servers)\n\"outbounds\": [{ \"protocol\": \"vless\", \"settings\": { \"vnext\": [ {\"address\":\"a.com\",\"port\":443,...}, {\"address\":\"b.com\",\"port\":443,...} ] } }]\n// after\n\"outbounds\": [\n  { \"protocol\": \"vless\", \"settings\": { \"vnext\": [ {\"address\":\"a.com\",\"port\":443,\"users\":[...]} ] }, \"tag\": \"vless-a\" },\n  { \"protocol\": \"vless\", \"settings\": { \"vnext\": [ {\"address\":\"b.com\",\"port\":443,\"users\":[...]} ] }, \"tag\": \"vless-b\" }\n]\n// plus a routing balancer over [\"vless-a\",\"vless-b\"]","handlingStrategy":"validation","validationCode":"func validateSingleVnext(cfg map[string]any) error {\n\toutbounds, _ := cfg[\"outbounds\"].([]any)\n\tfor _, ob := range outbounds {\n\t\tm, _ := ob.(map[string]any)\n\t\tif p, _ := m[\"protocol\"].(string); p != \"vless\" { continue }\n\t\tsettings, _ := m[\"settings\"].(map[string]any)\n\t\tif _, simplified := settings[\"address\"]; simplified { continue }\n\t\tvnext, _ := settings[\"vnext\"].([]any)\n\t\tif len(vnext) != 1 {\n\t\t\treturn fmt.Errorf(\"outbound %v: vless vnext must have exactly 1 entry, got %d\", m[\"tag\"], len(vnext))\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":"func isSingleVnext(settings map[string]any) bool {\n\tif _, ok := settings[\"address\"]; ok { return true }\n\tv, ok := settings[\"vnext\"].([]any)\n\treturn ok && len(v) == 1\n}","tryCatchPattern":null,"preventionTips":["Adopt the rule 'one outbound = one server' in config templates","Prefer the simplified outbound style (top-level address/port/id)","Use routing balancers, never extra vnext entries, for multi-server failover"],"tags":["vless","outbound","vnext","balancer","config","validation","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}