{"record":{"id":"848ef850c7f3d0af","repo":"XTLS/Xray-core","slug":"failed-to-build-httpupgrade-config","errorCode":null,"errorMessage":"Failed to build HTTPUpgrade config.","messagePattern":"Failed to build HTTPUpgrade config\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_internet.go","lineNumber":178,"sourceCode":"\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"grpc\",\n\t\t\tSettings:     serial.ToTypedMessage(gs),\n\t\t})\n\t}\n\tif c.WSSettings != nil {\n\t\tts, err := c.WSSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build WebSocket config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"websocket\",\n\t\t\tSettings:     serial.ToTypedMessage(ts),\n\t\t})\n\t}\n\tif c.HTTPUPGRADESettings != nil {\n\t\ths, err := c.HTTPUPGRADESettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build HTTPUpgrade config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"httpupgrade\",\n\t\t\tSettings:     serial.ToTypedMessage(hs),\n\t\t})\n\t}\n\tif c.HysteriaSettings != nil {\n\t\ths, err := c.HysteriaSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build Hysteria config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"hysteria\",\n\t\t\tSettings:     serial.ToTypedMessage(hs),\n\t\t})\n\t}\n\tif c.SocketSettings != nil {\n\t\tss, err := c.SocketSettings.Build()","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_internet.go#L160-L196","documentation":"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.","triggerScenarios":"An httpupgradeSettings block with an invalid 'path' (no leading '/'), bad 'host' value, or header entries that fail validation.","commonSituations":"Configs migrated from v2ray httpupgrade examples; missing path defaults on forks with stricter validation.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if _, err := streamCfg.Build(); err != nil {\n    if strings.Contains(err.Error(), \"Failed to build HTTPUpgrade config\") {\n        return fmt.Errorf(\"httpupgrade settings invalid: %w\", errors.Unwrap(err))\n    }\n}","preventionTips":["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."],"tags":["go","xray","config","httpupgrade","transport","error-chaining"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}