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

Inspect the chained base error for the failing WS field.

Failed to build WebSocket config.

Error message

Failed to build WebSocket config.

What it means

Wrapper thrown when streamSettings contains wsSettings whose Build() fails. The concrete WebSocket error (bad path, invalid headers, wrong early-data settings) is chained via .Base(err). Note the websocket transport itself is deprecated in favor of XHTTP, which emits a separate warning before this build is attempted.

Source

Thrown at infra/conf/transport_internet.go:168

		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "mkcp",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.GRPCSettings != nil {
		gs, err := c.GRPCSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build gRPC config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "grpc",
			Settings:     serial.ToTypedMessage(gs),
		})
	}
	if c.WSSettings != nil {
		ts, err := c.WSSettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build WebSocket config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "websocket",
			Settings:     serial.ToTypedMessage(ts),
		})
	}
	if c.HTTPUPGRADESettings != nil {
		hs, err := c.HTTPUPGRADESettings.Build()
		if err != nil {
			return nil, errors.New("Failed to build HTTPUpgrade config.").Base(err)
		}
		config.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{
			ProtocolName: "httpupgrade",
			Settings:     serial.ToTypedMessage(hs),
		})
	}
	if c.HysteriaSettings != nil {
		hs, err := c.HysteriaSettings.Build()

View on GitHub (pinned to 7d214f8b09)

Solutions

Inspect the chained base error for the failing WS field.
Normalize path to start with '/' and clean up headers.
Consider migrating to httpupgrade or XHTTP since websocket is deprecated here.

Defensive patterns

Strategy: try-catch

Try / catch

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

Prevention

Root every ws path with '/'.
Type-check header maps as map[string]string before serialization.
Plan migration off websocket — it is deprecated in favor of XHTTP here.

When it happens

Trigger: wsSettings with a path lacking a leading '/', malformed request headers, or an invalid maxEarlyData/earlyDataHeaderName combination.

Common situations: Legacy websocket configs carried forward; path values like "ws" instead of "/ws"; subscription-generated header maps with non-string values.

Related errors

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