{"record":{"id":"648a811bc4257dfd","repo":"XTLS/Xray-core","slug":"failed-to-build-xhttp-config","errorCode":null,"errorMessage":"Failed to build XHTTP config.","messagePattern":"Failed to build XHTTP config\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_internet.go","lineNumber":138,"sourceCode":"\t\tc.TCPSettings = c.RAWSettings\n\t}\n\tif c.TCPSettings != nil {\n\t\tts, err := c.TCPSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build RAW config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"tcp\",\n\t\t\tSettings:     serial.ToTypedMessage(ts),\n\t\t})\n\t}\n\tif c.XHTTPSettings != nil {\n\t\tc.SplitHTTPSettings = c.XHTTPSettings\n\t}\n\tif c.SplitHTTPSettings != nil {\n\t\ths, err := c.SplitHTTPSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build XHTTP config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"splithttp\",\n\t\t\tSettings:     serial.ToTypedMessage(hs),\n\t\t})\n\t}\n\tif c.KCPSettings != nil {\n\t\tts, err := c.KCPSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build mKCP config.\").Base(err)\n\t\t}\n\t\tconfig.TransportSettings = append(config.TransportSettings, &internet.TransportConfig{\n\t\t\tProtocolName: \"mkcp\",\n\t\t\tSettings:     serial.ToTypedMessage(ts),\n\t\t})\n\t}\n\tif c.GRPCSettings != nil {\n\t\tgs, err := c.GRPCSettings.Build()","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_internet.go#L120-L156","documentation":"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.","triggerScenarios":"An xhttpSettings/splithttpSettings object with invalid 'mode', a path not starting with '/', or unsupported stream-upgrade H1 fields on this fork.","commonSituations":"Copying XHTTP examples from upstream Xray that use modes/fields this fork removed; path typos missing the leading slash.","solutions":["Check the chained base error for the offending XHTTP field.","Use the 'xhttpSettings' key spelling and a path beginning with '/'.","Strip advanced H2/H3 options and retest with a minimal block."],"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 XHTTP config\") {\n        return fmt.Errorf(\"xhttp settings invalid: %w\", errors.Unwrap(err))\n    }\n}","preventionTips":["Use xhttpSettings/splithttpSettings paths starting with '/'.","Avoid copying upstream Xray XHTTP options not supported by this fork.","Start from a minimal XHTTP block and add options incrementally."],"tags":["go","xray","config","xhttp","transport","error-chaining"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}