What causes "Failed to build REALITY config." in XTLS/Xray-core?

Read the chained base error to identify the offending REALITY field.

Failed to build REALITY config.

Error message

Failed to build REALITY config.

What it means

Wrapper thrown when security is "reality" and the realitySettings object fails its own Build(). The underlying cause is chained via .Base(err) — typically invalid public/private key pairs, bad shortId hex, or an unusable dest/serverName. The REALITY-specific details are in the base error, not this message.

Source

Thrown at infra/conf/transport_internet.go:108

			tlsSettings = &TLSConfig{}
		}
		ts, err := tlsSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build TLS config.").Base(err)
		}
		tm := serial.ToTypedMessage(ts)
		config.SecuritySettings = append(config.SecuritySettings, tm)
		config.SecurityType = tm.Type
	case "reality":
		if config.ProtocolName != "tcp" && config.ProtocolName != "splithttp" && config.ProtocolName != "grpc" {
			return nil, errors.New("REALITY only supports RAW, XHTTP and gRPC for now.")
		}
		if c.REALITYSettings == nil {
			return nil, errors.New(`REALITY: Empty "realitySettings".`)
		}
		ts, err := c.REALITYSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build REALITY config.").Base(err)
		}
		tm := serial.ToTypedMessage(ts)
		config.SecuritySettings = append(config.SecuritySettings, tm)
		config.SecurityType = tm.Type
	case "xtls":
		return nil, errors.PrintRemovedFeatureError(`Legacy XTLS`, `xtls-rprx-vision with TLS or REALITY`)
	default:
		return nil, errors.New(`Unknown security "` + c.Security + `".`)
	}

	if c.RAWSettings != nil {
		c.TCPSettings = c.RAWSettings
	}
	if c.TCPSettings != nil {
		ts, err := c.TCPSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build RAW config.").Base(err)
		}

View on GitHub (pinned to 7d214f8b09)

Solutions

Read the chained base error to identify the offending REALITY field.
Regenerate/re-copy the x25519 key pair and shortId from the server output.
Validate key length and hex format before deploying.

Defensive patterns

Strategy: try-catch

Try / catch

if _, err := streamCfg.Build(); err != nil {
    if base := errors.Unwrap(err); base != nil && strings.Contains(err.Error(), "Failed to build REALITY config") {
        return fmt.Errorf("reality settings invalid: %w", base)
    }
}

Prevention

Validate x25519 keys decode to 32 bytes before config load.
Check shortId is valid hex of expected length.
Log base errors from wrapper chains; the top message alone is not actionable.

When it happens

Trigger: realitySettings with a malformed x25519 public key, non-hex shortId, empty serverName/dest, or spider parameters out of range.

Common situations: Truncated base64url keys pasted from subscriptions; shortId with '0x' prefix or odd length; serverName left empty on the server side.

Related errors

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