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

Inspect the wrapped/base error for the underlying TLS cause and fix that field.

Failed to build TLS config.

Error message

Failed to build TLS config.

What it means

Wrapper thrown by StreamConfig security building when streamSettings.security is "tls" and the nested tlsSettings object fails its own Build(). The original TLS error is attached via .Base(err); the real cause is inside the TLSConfig build (bad certificates, invalid ALPN, etc.). If tlsSettings is absent an empty TLSConfig{} is built, so this can also surface defaults validation.

Source

Thrown at infra/conf/transport_internet.go:94

	}
	if c.Network != nil {
		protocol, err := c.Network.Build()
		if err != nil {
			return nil, err
		}
		config.ProtocolName = protocol
	}

	switch strings.ToLower(c.Security) {
	case "", "none":
	case "tls":
		tlsSettings := c.TLSSettings
		if tlsSettings == nil {
			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

View on GitHub (pinned to 7d214f8b09)

Solutions

Inspect the wrapped/base error for the underlying TLS cause and fix that field.
Validate certificate files exist and parse as PEM before starting.
If TLS is not intended, set security to "none" or remove the tlsSettings block.

Defensive patterns

Strategy: try-catch

Try / catch

if _, err := streamCfg.Build(); err != nil {
    if strings.Contains(err.Error(), "Failed to build TLS config") {
        // unwrap errors.Unwrap(err) to reach the concrete TLS cause and report it
    }
    return err
}

Prevention

Pre-parse certificate files with tls.LoadX509KeyPair in a pre-flight step.
Always log the chained base error, not just the wrapper message.
Validate ALPN entries against the allowed list before build.

When it happens

Trigger: security:"tls" together with malformed certificate paths, invalid ALPN entries, or bad key values inside tlsSettings; omitted tlsSettings that still fails default validation.

Common situations: Wrong certificate file paths after moving configs; PEM blocks pasted with corruption; ALPN values not in the allowed list.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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