XTLS/Xray-core · error

empty "privateKey"

Error message

empty "privateKey"

What it means

Thrown by the REALITY builder when the privateKey field is an empty string. The private key is the server's long-term REALITY identity (x25519); without it no handshakes can be authenticated, so the builder refuses.

Source

Thrown at infra/conf/transport_security.go:98

				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)
				}
			}
			errors.LogWarning(context.Background(), `REALITY: Changing "minClientVer" will increase the likelihood of your server's IP being blocked by the GFW`)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Generate a key pair with 'xray x25519' and put the private key on the server.
2. If editing a client config, remove privateKey and use "publicKey" + "fingerprint" instead.

Example fix

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

if reality.PrivateKey == "" {
    return errors.New("server-side REALITY requires privateKey (generate with `xray x25519`)")
}

When it happens

Trigger: Omitting privateKey in realitySettings or setting it to "".

Common situations: Client-side configs accidentally including a realitySettings block (privateKey is server-only; clients use publicKey/fingerprint), or the key never generated.

Related errors

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

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