XTLS/Xray-core · error

empty "serverNames"

Error message

empty "serverNames"

What it means

Thrown by the REALITY builder when the serverNames array is empty. REALITY must know which SNI values to intercept and serve; with no server names the TLS handshake cannot be matched, so the config is rejected.

Source

Thrown at infra/conf/transport_security.go:95

					s = string(fullAddr)
				}
			default:
				if _, err = strconv.Atoi(s); err == nil {
					s = "localhost:" + s
				}
				if _, _, err = net.SplitHostPort(s); err == nil {
					c.Type = "tcp"
				}
			}
		}
		if c.Type == "" {
			return nil, errors.New(`please fill in a valid value for "target"`)
		}
		if c.Xver > 2 {
			return nil, errors.New(`invalid PROXY protocol version, "xver" only accepts 0, 1, 2`)
		}
		if len(c.ServerNames) == 0 {
			return nil, errors.New(`empty "serverNames"`)
		}
		if c.PrivateKey == "" {
			return nil, errors.New(`empty "privateKey"`)
		}
		if config.PrivateKey, err = base64.RawURLEncoding.DecodeString(c.PrivateKey); err != nil || len(config.PrivateKey) != 32 {
			return nil, errors.New(`invalid "privateKey": `, c.PrivateKey)
		}
		if c.MinClientVer != "" {
			config.MinClientVer = make([]byte, 3)
			var u uint64
			for i, s := range strings.Split(c.MinClientVer, ".") {
				if i == 3 {
					return nil, errors.New(`invalid "minClientVer": `, c.MinClientVer)
				}
				if u, err = strconv.ParseUint(s, 10, 8); err != nil {
					return nil, errors.New(`"minClientVer[`, i, `]" should be less than 256`)
				} else {
					config.MinClientVer[i] = byte(u)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Add at least one SNI matching your target site, e.g. "serverNames": ["www.microsoft.com"].
2. Make sure the SNI is consistent with the target/dest site so the masquerade is credible.

Example fix

// before
"realitySettings": { "target": "www.microsoft.com:443" }
// after
"realitySettings": { "target": "www.microsoft.com:443", "serverNames": ["www.microsoft.com"] }

if len(reality.ServerNames) == 0 {
    return errors.New("reality requires at least one serverName")
}

When it happens

Trigger: Omitting serverNames from realitySettings, or providing "serverNames": [].

Common situations: Migration from常规 TLS configs where serverName was optional client-side; on the server side for REALITY it is mandatory.

Related errors

• REALITY: Empty "realitySettings".
• please fill in a valid value for "target"
• invalid PROXY protocol version, "xver" only accepts 0, 1, 2
• empty "privateKey"
• invalid "privateKey":

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