{"record":{"id":"204c4a1ffa247ca2","repo":"XTLS/Xray-core","slug":"failed-to-build-hysteria-config","errorCode":null,"errorMessage":"Failed to build Hysteria config.","messagePattern":"Failed to build Hysteria config\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_internet.go","lineNumber":188,"sourceCode":"\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()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build sockopt.\").Base(err)\n\t\t}\n\t\tconfig.SocketSettings = ss\n\t}\n\n\tif c.FinalMask != nil {\n\t\tfor _, mask := range c.FinalMask.Tcp {\n\t\t\tu, err := mask.Build(true)\n\t\t\tif err != nil {","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_internet.go#L170-L206","documentation":"Thrown while building the top-level streamSettings when the 'hysteria' transport block is present but HysteriaSettings.Build() fails. This is a wrapper error: the real cause is chained via .Base(err) and comes from the Hysteria transport config builder itself (e.g. invalid bandwidth strings or missing required fields). It aborts config compilation before any network activity starts.","triggerScenarios":"A JSON config with \"streamSettings\": {\"transport\": \"hysteria\", \"transportSettings\": {...}} (parsed into HysteriaSettings) whose inner Build() returns an error, e.g. a malformed BrutalUp/BrutalDown bandwidth value or another invalid sub-field.","commonSituations":"Copying a Hysteria block from a different fork/version whose schema differs; typoing a bandwidth string (\"100mbps\" vs \"100 mbps\"); enabling hysteria transport without required parameters.","solutions":["Read the chained cause after 'Failed to build Hysteria config.': the Base(err) text names the exact invalid field; fix that field.","Compare your hysteria transportSettings keys against the HysteriaSettings struct in infra/conf (field names and units).","Regenerate/validate the config with `xray run -test -c config.json` (or equivalent) before deploying."],"exampleFix":"// before\n\"transportSettings\": { \"brutalUp\": \"100mbps\" } // malformed/unsupported value\n// after\n\"transportSettings\": { \"brutalUp\": \"100 mbps\" } // correct syntax per Bandwidth parser","handlingStrategy":"try-catch","validationCode":"// Pre-validate the hysteria block shape before Build()\nfunc hysteriaSettingsLookSane(h map[string]any) bool {\n    if h == nil { return true } // absent is fine\n    for _, k := range []string{\"brutalUp\", \"brutalDown\"} {\n        if v, ok := h[k]; ok && v == nil { return false }\n    }\n    return true\n}","typeGuard":"func isHysteriaBlockPresent(s map[string]any) bool {\n    ts, ok := s[\"transportSettings\"].(map[string]any)\n    if !ok { return false }\n    _, present := ts[\"hysteria\"]\n    return present\n}","tryCatchPattern":"cfg, err := jsonToStreamSettings(raw)\nif err != nil {\n    if strings.Contains(err.Error(), \"Failed to build Hysteria config.\") {\n    // unwrap errors.Unwrap(err) to reach the field-level cause and report it\n    }\n    return fmt.Errorf(\"config build failed: %w\", err)\n}","preventionTips":["Run `xray run -test -c config.json` in CI for every config change.","Keep hysteria transportSettings schema in sync with the exact binary version deployed.","Log the full error chain (use %w / errors.Unwrap), not just the top-level message."],"tags":["go","xray","config","hysteria","validation"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}