{"record":{"id":"b66a4a1919acd6e2","repo":"XTLS/Xray-core","slug":"vless-vnext-users-should-have-one-and-only-one","errorCode":null,"errorMessage":"VLESS vnext: \"users\" should have one and only one member. Multiple members in \"users\" should use multiple VLESS outbounds and routing balancer instead","messagePattern":"VLESS vnext: \"users\" should have one and only one member\\. Multiple members in \"users\" should use multiple VLESS outbounds and routing balancer instead","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/vless.go","lineNumber":280,"sourceCode":"\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 {\n\t\t\t\tif err := json.Unmarshal(rawUser, user); err != nil {\n\t\t\t\t\treturn nil, errors.New(`VLESS users: invalid user`).Base(err)\n\t\t\t\t}\n\t\t\t}\n\t\t\taccount := new(vless.Account)\n\t\t\tif c.Address != nil {\n\t\t\t\taccount.Id = c.Id","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/vless.go#L262-L298","documentation":"Thrown by VLessOutboundConfig.Build() when the \"users\" array inside a vnext entry does not contain exactly one member. One VLESS outbound authenticates as exactly one user; multiple credentials must be split across multiple outbounds (optionally behind a routing balancer). An empty users array is rejected for the same reason.","triggerScenarios":"\"vnext\":[{\"address\":\"a.com\",\"port\":443,\"users\":[]}] or users with two credential objects; commonly left over from editing an inbound clients list into an outbound.","commonSituations":"Copying the inbound \"clients\" array (which legitimately holds many users) into the outbound \"users\" field; deleting a user and leaving an empty array; misunderstanding that outbound users are credentials for dialing out, not for accepting.","solutions":["Keep exactly one user object in outbound \"users\"","If you need several identities/servers, use multiple outbounds plus a routing balancer","Make sure the array is not empty — at least one {\"id\":\"uuid\",\"encryption\":\"none\"} is required"],"exampleFix":"// before\n\"users\": [ {\"id\":\"uuid-a\",\"encryption\":\"none\"}, {\"id\":\"uuid-b\",\"encryption\":\"none\"} ]\n// after\n\"users\": [ {\"id\":\"uuid-a\",\"encryption\":\"none\"} ]","handlingStrategy":"validation","validationCode":"func validateSingleUserPerVnext(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\tvnext, _ := settings[\"vnext\"].([]any)\n\t\tfor _, v := range vnext {\n\t\t\tep, _ := v.(map[string]any)\n\t\t\tusers, _ := ep[\"users\"].([]any)\n\t\t\tif len(users) != 1 {\n\t\t\t\treturn fmt.Errorf(\"outbound %v: vless vnext.users must have exactly 1 entry, got %d\", m[\"tag\"], len(users))\n\t\t\t}\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":"func hasExactlyOneUser(ep map[string]any) bool {\n\tu, ok := ep[\"users\"].([]any)\n\treturn ok && len(u) == 1\n}","tryCatchPattern":null,"preventionTips":["Never paste inbound clients arrays into outbound users","One credential per outbound; balancers for variety","Assert len(users)==1 in config generators before emitting JSON"],"tags":["vless","outbound","users","config","validation","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}