XTLS/Xray-core · error

VLESS vnext: "address" is not set

Error message

VLESS vnext: "address" is not set

What it means

Thrown by VLessOutboundConfig.Build() while iterating the single vnext entry when its "address" field is missing. Address is the only required field of a vnext object (port defaults to 0, users is checked separately), and a nil Address makes the endpoint unbuildable.

Source

Thrown at infra/conf/vless.go:277

// Build implements Buildable
func (c *VLessOutboundConfig) Build() (proto.Message, error) {
	config := new(outbound.Config)
	if c.Address != nil {
		c.Vnext = []*VLessOutboundVnext{
			{
				Address: c.Address,
				Port:    c.Port,
				Users:   []json.RawMessage{{}},
			},
		}
	}
	if len(c.Vnext) != 1 {
		return 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`)
	}
	for _, rec := range c.Vnext {
		if rec.Address == nil {
			return nil, errors.New(`VLESS vnext: "address" is not set`)
		}
		if len(rec.Users) != 1 {
			return 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`)
		}
		spec := &protocol.ServerEndpoint{
			Address: rec.Address.Build(),
			Port:    uint32(rec.Port),
		}
		for _, rawUser := range rec.Users {
			user := new(protocol.User)
			if c.Address != nil {
				user.Level = c.Level
				user.Email = c.Email
			} else {
				if err := json.Unmarshal(rawUser, user); err != nil {
					return nil, errors.New(`VLESS users: invalid user`).Base(err)
				}
			}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Add "address":"your.server.example" to the vnext object
2. Verify the key is exactly "address" and the value is a non-empty string or address object
3. Prefer the simplified outbound style ("address"/"port" at top level) to reduce nesting mistakes

Example fix

// before
"vnext": [{ "port": 443, "users": [{ "id": "...", "encryption": "none" }] }]
// after
"vnext": [{ "address": "server.example", "port": 443, "users": [{ "id": "...", "encryption": "none" }] }]

func validateVnextAddress(cfg map[string]any) error {
	outbounds, _ := cfg["outbounds"].([]any)
	for _, ob := range outbounds {
		m, _ := ob.(map[string]any)
		if p, _ := m["protocol"].(string); p != "vless" { continue }
		settings, _ := m["settings"].(map[string]any)
		vnext, _ := settings["vnext"].([]any)
		for _, v := range vnext {
			ep, _ := v.(map[string]any)
			if addr, ok := ep["address"].(string); !ok || addr == "" {
				return fmt.Errorf("outbound %v: vnext entry missing address", m["tag"])
			}
		}
	}
	return nil
}

func vnextHasAddress(ep map[string]any) bool {
	a, ok := ep["address"]
	if s, isStr := a.(string); isStr { return s != "" }
	_, isObj := a.(map[string]any)
	return ok && isObj
}

When it happens

Trigger: "vnext":[{"port":443,"users":[...]}] with no "address" key; address misspelled ("server", "host", "add"); address set to null in JSON.

Common situations: Renaming fields when converting between share-link formats and raw JSON; partial hand-editing; generators that emit an empty object as a placeholder.

Related errors

• VLESS settings: "vnext" should have one and only one member.
• VMess vnext: "address" is not set
• invalid redirect address: {}
• VLESS vnext: "users" should have one and only one member. Mu
• VLESS users: please add/set "encryption":"none" for every us

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/1f576bb2658efc87. Report an issue: GitHub.