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

Check the base error for the specific HTTPUpgrade field.

Failed to build HTTPUpgrade config.

Error message

Failed to build HTTPUpgrade config.

What it means

Wrapper thrown when streamSettings contains httpupgradeSettings whose Build() fails. The underlying HTTPUpgrade error (typically path or header validation) is attached with .Base(err). HTTPUpgrade is also flagged as deprecated in favor of XHTTP H2/H3 before the build runs.

Source

Thrown at infra/conf/transport_internet.go:178

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

View on GitHub (pinned to 7d214f8b09)

Solutions

Check the base error for the specific HTTPUpgrade field.
Set path to "/" or a valid rooted path and a non-empty host.
Plan migration to splithttp/xhttp since httpupgrade is deprecated here.

Defensive patterns

Strategy: try-catch

Try / catch

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

Prevention

Set a valid rooted path and non-empty host for httpupgrade.
Validate headers as string maps before build.
Track the deprecation of httpupgrade and migrate to splithttp/xhttp.

When it happens

Trigger: An httpupgradeSettings block with an invalid 'path' (no leading '/'), bad 'host' value, or header entries that fail validation.

Common situations: Configs migrated from v2ray httpupgrade examples; missing path defaults on forks with stricter validation.

Related errors

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