{"record":{"id":"4a515ff05098a939","repo":"XTLS/Xray-core","slug":"failed-to-build-reality-config","errorCode":null,"errorMessage":"Failed to build REALITY config.","messagePattern":"Failed to build REALITY config\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/transport_internet.go","lineNumber":108,"sourceCode":"\t\t\ttlsSettings = &TLSConfig{}\n\t\t}\n\t\tts, err := tlsSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build TLS config.\").Base(err)\n\t\t}\n\t\ttm := serial.ToTypedMessage(ts)\n\t\tconfig.SecuritySettings = append(config.SecuritySettings, tm)\n\t\tconfig.SecurityType = tm.Type\n\tcase \"reality\":\n\t\tif config.ProtocolName != \"tcp\" && config.ProtocolName != \"splithttp\" && config.ProtocolName != \"grpc\" {\n\t\t\treturn nil, errors.New(\"REALITY only supports RAW, XHTTP and gRPC for now.\")\n\t\t}\n\t\tif c.REALITYSettings == nil {\n\t\t\treturn nil, errors.New(`REALITY: Empty \"realitySettings\".`)\n\t\t}\n\t\tts, err := c.REALITYSettings.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"Failed to build REALITY config.\").Base(err)\n\t\t}\n\t\ttm := serial.ToTypedMessage(ts)\n\t\tconfig.SecuritySettings = append(config.SecuritySettings, tm)\n\t\tconfig.SecurityType = tm.Type\n\tcase \"xtls\":\n\t\treturn nil, errors.PrintRemovedFeatureError(`Legacy XTLS`, `xtls-rprx-vision with TLS or REALITY`)\n\tdefault:\n\t\treturn nil, errors.New(`Unknown security \"` + c.Security + `\".`)\n\t}\n\n\tif c.RAWSettings != nil {\n\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}","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/transport_internet.go#L90-L126","documentation":"Wrapper thrown when security is \"reality\" and the realitySettings object fails its own Build(). The underlying cause is chained via .Base(err) — typically invalid public/private key pairs, bad shortId hex, or an unusable dest/serverName. The REALITY-specific details are in the base error, not this message.","triggerScenarios":"realitySettings with a malformed x25519 public key, non-hex shortId, empty serverName/dest, or spider parameters out of range.","commonSituations":"Truncated base64url keys pasted from subscriptions; shortId with '0x' prefix or odd length; serverName left empty on the server side.","solutions":["Read the chained base error to identify the offending REALITY field.","Regenerate/re-copy the x25519 key pair and shortId from the server output.","Validate key length and hex format before deploying."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if _, err := streamCfg.Build(); err != nil {\n    if base := errors.Unwrap(err); base != nil && strings.Contains(err.Error(), \"Failed to build REALITY config\") {\n        return fmt.Errorf(\"reality settings invalid: %w\", base)\n    }\n}","preventionTips":["Validate x25519 keys decode to 32 bytes before config load.","Check shortId is valid hex of expected length.","Log base errors from wrapper chains; the top message alone is not actionable."],"tags":["go","xray","config","reality","error-chaining","crypto"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}