{"record":{"id":"113002915d7ad9be","repo":"XTLS/Xray-core","slug":"failed-to-build-downloadsettings","errorCode":null,"errorMessage":"Failed to build \"downloadSettings\".","messagePattern":"Failed to build \"downloadSettings\"\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_method.go","lineNumber":505,"sourceCode":"\t\tSessionIDTable:       c.SessionIDTable,\n\t\tSessionIDLength:      newRangeConfig(c.SessionIDLength),\n\t\tXmux: &splithttp.XmuxConfig{\n\t\t\tMaxConcurrency:   newRangeConfig(c.Xmux.MaxConcurrency),\n\t\t\tMaxConnections:   newRangeConfig(c.Xmux.MaxConnections),\n\t\t\tCMaxReuseTimes:   newRangeConfig(c.Xmux.CMaxReuseTimes),\n\t\t\tHMaxRequestTimes: newRangeConfig(c.Xmux.HMaxRequestTimes),\n\t\t\tHMaxReusableSecs: newRangeConfig(c.Xmux.HMaxReusableSecs),\n\t\t\tHKeepAlivePeriod: c.Xmux.HKeepAlivePeriod,\n\t\t},\n\t}\n\n\tif c.DownloadSettings != nil {\n\t\tif c.Mode == \"stream-one\" {\n\t\t\treturn nil, errors.New(`Can not use \"downloadSettings\" in \"stream-one\" mode.`)\n\t\t}\n\t\tvar err error\n\t\tif config.DownloadSettings, err = c.DownloadSettings.Build(); err != nil {\n\t\t\treturn nil, errors.New(`Failed to build \"downloadSettings\".`).Base(err)\n\t\t}\n\t}\n\n\treturn config, nil\n}\n\nfunc roomSize(tableSize int, min, max int32) *big.Int {\n\tbase := big.NewInt(int64(tableSize))\n\tsum := new(big.Int)\n\tterm := new(big.Int)\n\tfor k := min; k <= max; k++ {\n\t\tterm.Exp(base, big.NewInt(int64(k)), nil)\n\t\tsum.Add(sum, term)\n\t}\n\treturn sum\n}\n\ntype KCPConfig struct {","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_method.go#L487-L523","documentation":"When \"downloadSettings\" is present and mode is not stream-one, SplitHTTPConfig.Build() calls DownloadSettings.Build() (a full StreamConfig build) and wraps any failure at transport_method.go:503-506. The base error identifies the nested failure: bad transport name, invalid transportSettings for the chosen download transport (tcp/kcp/ws/http/grpc etc.), invalid security settings, or invalid proxySettings.","triggerScenarios":"\"downloadSettings\": {\"transportSettings\": {\"transport\": \"h2\"}} where h2 is not a registered transport; or a tcp downloadSettings with an invalid header block (reuses error 400/401 logic); or \"security\": \"tls\" with a malformed tlsSettings object.","commonSituations":"Splitting up/down transports across CDNs and typo-ing the download transport type; downloadSettings copied from an outbound streamSettings retaining fields invalid in this position; version drift where a transport was renamed.","solutions":["Read the base (chained) error — it is the inner StreamConfig build failure and names the real problem","Fix the nested transportSettings/tlsSettings per that inner error's documentation","Ensure \"transport\" inside downloadSettings.transportSettings is a registered stream transport (tcp, rawtcp, ws, http, h2, grpc, gun, splithttp, kcp...)","Simplify: omit downloadSettings to use the same transport for both directions while testing"],"exampleFix":"// before\n\"downloadSettings\": { \"transportSettings\": { \"transport\": \"h3\" } }\n// after\n\"downloadSettings\": { \"transportSettings\": { \"transport\": \"http\", \"transportSettings\": { \"host\": \"dl.example.com\", \"path\": /dl\" } } }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Go: wrap and unwrap the chained base error to reach the inner StreamConfig failure\nif _, err := cfg.Build(); err != nil {\n\tif strings.Contains(err.Error(), `Failed to build \"downloadSettings\"`) {\n\t\t// err chain's Base holds the nested cause; log the full chain\n\t\tlog.Printf(\"nested download transport invalid: %v\", err)\n\t}\n\treturn err\n}","preventionTips":["Treat downloadSettings as a full StreamConfig: validate its transport name and settings the same way as a top-level stream","Read the base error — it names the inner field that failed","Test with downloadSettings omitted first, then add it back"],"tags":["config","splithttp","download-settings","nested-config"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}