XTLS/Xray-core · error

invalid address:

Error message

invalid address: 

What it means

Thrown by Address.UnmarshalJSON in infra/conf/common.go when the JSON value for an address field cannot be unmarshaled into a plain JSON string. The value must be a JSON string (it may carry an env: prefix which is resolved via platform.NewEnvFlag). If it is a number, object, array, or malformed JSON, this error wraps the underlying json error.

Source

Thrown at infra/conf/common.go:57

		return nil
	}
	return errors.New("unknown format of a string list: " + string(data))
}

type Address struct {
	net.Address
}

// MarshalJSON implements encoding/json.Marshaler.MarshalJSON
func (v *Address) MarshalJSON() ([]byte, error) {
	return json.Marshal(v.Address.String())
}

// UnmarshalJSON implements encoding/json.Unmarshaler.UnmarshalJSON
func (v *Address) UnmarshalJSON(data []byte) error {
	var rawStr string
	if err := json.Unmarshal(data, &rawStr); err != nil {
		return errors.New("invalid address: ", string(data)).Base(err)
	}
	if strings.HasPrefix(rawStr, "env:") {
		rawStr = platform.NewEnvFlag(rawStr[4:]).GetValue(func() string { return "" })
	}
	v.Address = net.ParseAddress(rawStr)

	return nil
}

func (v *Address) Build() *net.IPOrDomain {
	return net.NewIPOrDomain(v.Address)
}

type Network string

func (v Network) Build() net.Network {
	switch strings.ToLower(string(v)) {
	case "tcp":

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Quote the address value: "address": "8.8.8.8" instead of 8.8.8.8
2. If you need a domain + port, keep only the host in the address field; ports go in their own 'port' field
3. For env substitution use the string form "env:MY_HOST" and ensure the variable is exported
4. Inspect the wrapped json error (the .Base(err) chain) to see the exact JSON syntax problem

Example fix

// before
"address": 1.2.3.4

// after
"address": "1.2.3.4"

func isValidAddressJSON(raw []byte) bool {
    var s string
    return json.Unmarshal(raw, &s) == nil // Address accepts any string; net.ParseAddress decides later
}

if err := json.Unmarshal(data, &addr); err != nil {
    if strings.Contains(err.Error(), "invalid address") {
        return fmt.Errorf("address field must be a JSON string, got: %s", data)
    }
    return err
}

When it happens

Trigger: Any field typed conf.Address (server 'address', DNS nameserver address, stream security SNI-ish fields) given a non-string: "address": 8.8.8.8 (unquoted IP becomes a number or two numbers), "address": ["a","b"], or "address": {"host":"x"}.

Common situations: Forgetting quotes around a numeric IP so JSON parses it as a number (8.8.8.8 unquoted is actually invalid JSON with two dots, but 1.2 becomes a number); pasting an object form where only a string is accepted; env: variable names that expand to an empty string are accepted here but fail later at net.ParseAddress.

Related errors

• unknown format of a string list:
• Invalid integer range, expected either string of form "1-2"
• invalid fakedns config
• invalid redirect address: {}
• VLESS vnext: "address" is not set

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