XTLS/Xray-core · error

Failed to build RAW config.

Error message

Failed to build RAW config.

What it means

Wrapper thrown when streamSettings contains tcpSettings (or its alias rawSettings) whose Build() fails. The underlying RAW/TCP transport error (e.g. invalid header settings) is chained with .Base(err). Note rawSettings is copied onto tcpSettings before the build, so either key can trigger it.

Source

Thrown at infra/conf/transport_internet.go:125

		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)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "tcp",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.XHTTPSettings != nil {
		c.SplitHTTPSettings = c.XHTTPSettings
	}
	if c.SplitHTTPSettings != nil {
		hs, err := c.SplitHTTPSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build XHTTP config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "splithttp",
			Settings:     serial.ToTypedMessage(hs),
		})

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the base error for the exact RAW-setting field at fault.
2. Prefer the 'rawSettings' key name (newer) over 'tcpSettings'.
3. Simplify: remove the header block to test with default RAW settings.

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

When it happens

Trigger: A tcpSettings/rawSettings block with invalid header type or malformed header request fields triggers this; the detailed cause is in the base error.

Common situations: Using the older 'tcpSettings' key on a fork that expects 'rawSettings' with incompatible values; bad header objects copied from old configs.

Related errors

• Failed to build XHTTP config.
• Failed to build mKCP config.
• Failed to build gRPC config.
• Failed to build WebSocket config.
• Failed to build HTTPUpgrade config.

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