XTLS/Xray-core · error

Failed to build XHTTP config.

Error message

Failed to build XHTTP config.

What it means

Wrapper thrown when streamSettings contains splithttpSettings (or its alias xhttpSettings) whose Build() fails. The real cause — bad path, mode, or extra XHTTP fields — is chained via .Base(err). xhttpSettings is copied onto splithttpSettings first, so both key spellings route here.

Source

Thrown at infra/conf/transport_internet.go:138

		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),
		})
	}
	if c.KCPSettings != nil {
		ts, err := c.KCPSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build mKCP config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "mkcp",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.GRPCSettings != nil {
		gs, err := c.GRPCSettings.Build()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the chained base error for the offending XHTTP field.
2. Use the 'xhttpSettings' key spelling and a path beginning with '/'.
3. Strip advanced H2/H3 options and retest with a minimal block.

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

When it happens

Trigger: An xhttpSettings/splithttpSettings object with invalid 'mode', a path not starting with '/', or unsupported stream-upgrade H1 fields on this fork.

Common situations: Copying XHTTP examples from upstream Xray that use modes/fields this fork removed; path typos missing the leading slash.

Related errors

• Failed to build RAW 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/648a811bc4257dfd. Report an issue: GitHub.