{"record":{"id":"5d248d09406b5b0f","repo":"redis/go-redis","slug":"ft-hybrid-shard-k-ratio-must-be-between-0-1-and-1","errorCode":null,"errorMessage":"FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0","messagePattern":"FT\\.HYBRID: SHARD_K_RATIO must be between 0\\.1 and 1\\.0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"search_commands.go","lineNumber":3920,"sourceCode":"\t\t\t\targs = append(args, vectorExpr.Method)\n\t\t\t\tif len(vectorExpr.MethodParams) > 0 {\n\t\t\t\t\t// MethodParams should be key-value pairs, count them\n\t\t\t\t\targs = append(args, len(vectorExpr.MethodParams))\n\t\t\t\t\targs = append(args, vectorExpr.MethodParams...)\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// SHARD_K_RATIO applies to the KNN method only (Redis 8.8+, cluster only).\n\t\t\t// Zero means \"unset\" and falls back to the server default of 1.0.\n\t\t\tif vectorExpr.ShardKRatio > 0 {\n\t\t\t\tif vectorExpr.Method != \"KNN\" {\n\t\t\t\t\tcmd := newFTHybridCmd(ctx, options, args...)\n\t\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.HYBRID: SHARD_K_RATIO requires KNN method\"))\n\t\t\t\t\treturn cmd\n\t\t\t\t}\n\t\t\t\tif vectorExpr.ShardKRatio < 0.1 || vectorExpr.ShardKRatio > 1.0 {\n\t\t\t\t\tcmd := newFTHybridCmd(ctx, options, args...)\n\t\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0\"))\n\t\t\t\t\treturn cmd\n\t\t\t\t}\n\t\t\t\targs = append(args, \"SHARD_K_RATIO\", vectorExpr.ShardKRatio)\n\t\t\t}\n\n\t\t\tif vectorExpr.Filter != \"\" {\n\t\t\t\targs = append(args, \"FILTER\", vectorExpr.Filter)\n\t\t\t}\n\n\t\t\tif vectorExpr.YieldScoreAs != \"\" {\n\t\t\t\targs = append(args, \"YIELD_SCORE_AS\", vectorExpr.YieldScoreAs)\n\t\t\t}\n\t\t}\n\n\t\t// Add combine/fusion options\n\t\tif options.Combine != nil {\n\t\t\t// Build combine parameters\n\t\t\tcombineParams := []interface{}{}","sourceCodeStart":3902,"sourceCodeEnd":3938,"githubUrl":"https://github.com/redis/go-redis/blob/c5cad058c72f58370553b48566302303cf8a2e89/search_commands.go#L3902-L3938","documentation":"FT.HYBRID validation error raised client-side before the command is sent. The SHARD_K_RATIO parameter (used with the KNN vector search method to control how many candidates each shard contributes in a cluster) must be a value between 0.1 and 1.0 inclusive. The go-redis client validates this bound while building the FT.HYBRID command and returns the command pre-populated with this error instead of sending an invalid request to Redis.","triggerScenarios":"Calling FT.HYBRID with a VectorExpr where ShardKRatio is set below 0.1 (e.g. 0.05) or above 1.0 (e.g. 1.5), while using the KNN vector method.","commonSituations":"Misreading SHARD_K_RATIO as a percentage (passing 15 instead of 0.15), copying a ratio from a config tuned for a different cluster, or computing the ratio dynamically with a formula that can exceed 1.0.","solutions":["Set ShardKRatio to a value in [0.1, 1.0], e.g. options.VectorExpr.ShardKRatio = 0.5","Clamp or validate the value before building options: if r < 0.1 { r = 0.1 }; if r > 1.0 { r = 1.0 }","Remove ShardKRatio entirely to use the server default"],"exampleFix":"// before\nopts := &FTHybridOptions{VectorExpr: &FTHybridVectorExpr{Method: \"KNN\", ShardKRatio: 1.5}}\n// after\nopts := &FTHybridOptions{VectorExpr: &FTHybridVectorExpr{Method: \"KNN\", ShardKRatio: 0.5}}","handlingStrategy":"validation","validationCode":"func validShardKRatio(r float64) bool { return r >= 0.1 && r <= 1.0 }\nif opts.VectorExpr != nil && opts.VectorExpr.ShardKRatio != 0 && !validShardKRatio(opts.VectorExpr.ShardKRatio) {\n    return fmt.Errorf(\"ShardKRatio %v outside [0.1, 1.0]\", opts.VectorExpr.ShardKRatio)\n}","typeGuard":null,"tryCatchPattern":"cmd := rdb.FTHybrid(ctx, opts, args...)\nif err := cmd.Err(); err != nil {\n    if strings.Contains(err.Error(), \"SHARD_K_RATIO\") { /* fix ratio and retry */ }\n    return err\n}","preventionTips":["Store SHARD_K_RATIO as a ratio (0.1-1.0), never a percentage","Clamp values at config-load time","Omit ShardKRatio when unsure to get server defaults"],"tags":["redis","search","ft-hybrid","parameter-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"c5cad058c72f58370553b48566302303cf8a2e89","analyzedAt":"2026-09-01T06:50:53.388Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}