XTLS/Xray-core · error

empty "shortIds"

Error message

empty "shortIds"

What it means

Thrown by the REALITY builder when the shortIds array is missing or empty. Short IDs are the per-client authorization tokens REALITY checks during the handshake; with none configured every client would be rejected, so the builder treats it as a config error.

Source

Thrown at infra/conf/transport_security.go:136

			config.MinClientVer = []byte{26, 3, 27} // change it at your own risk: https://github.com/XTLS/Xray-core/commit/af7eb68028732a8ee3c0e5d6ab2b8a657bb2e770
			errors.LogWarning(context.Background(), `REALITY: The default minimal client version is Xray-core v26.3.27, other clients may be refused to connect`)
		}
		if c.MaxClientVer != "" {
			config.MaxClientVer = make([]byte, 3)
			var u uint64
			for i, s := range strings.Split(c.MaxClientVer, ".") {
				if i == 3 {
					return nil, errors.New(`invalid "maxClientVer": `, c.MaxClientVer)
				}
				if u, err = strconv.ParseUint(s, 10, 8); err != nil {
					return nil, errors.New(`"maxClientVer[`, i, `]" should be less than 256`)
				} else {
					config.MaxClientVer[i] = byte(u)
				}
			}
		}
		if len(c.ShortIds) == 0 {
			return nil, errors.New(`empty "shortIds"`)
		}
		config.ShortIds = make([][]byte, len(c.ShortIds))
		for i, s := range c.ShortIds {
			if len(s) > 16 {
				return nil, errors.New(`too long "shortIds[`, i, `]": `, s)
			}
			config.ShortIds[i] = make([]byte, 8)
			if _, err = hex.Decode(config.ShortIds[i], []byte(s)); err != nil {
				return nil, errors.New(`invalid "shortIds[`, i, `]": `, s)
			}
		}
		config.Dest = s
		config.Type = c.Type
		config.Xver = c.Xver
		config.ServerNames = c.ServerNames
		config.MaxTimeDiff = c.MaxTimeDiff

		if c.Mldsa65Seed != "" {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Add at least one shortId, e.g. "shortIds": [""] (empty string allows clients without shortId) or a hex string like "0123456789abcdef".
2. Ensure the client's shortId matches one of the server's entries.

Example fix

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

if len(reality.ShortIds) == 0 {
    return errors.New("reality requires a non-empty shortIds array")
}

When it happens

Trigger: Omitting shortIds from server-side realitySettings or providing "shortIds": [].

Common situations: First REALITY server setup following a guide that skips shortIds, or a client config mistakenly deployed server-side (clients also carry shortId but the empty array still fails).

Related errors

• too long "shortIds[
• 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/b234b23b1659cb7c. Report an issue: GitHub.