{"id":"8fe2040344b7ee7e","repo":"go-redis/redis","slug":"ft-hybrid-shard-k-ratio-requires-knn-method","errorCode":null,"errorMessage":"FT.HYBRID: SHARD_K_RATIO requires KNN method","messagePattern":"FT\\.HYBRID: SHARD_K_RATIO requires KNN method","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"search_commands.go","lineNumber":3889,"sourceCode":"\t\t\t}\n\t\t\targs = append(args, \"$\"+paramName)\n\t\t\tparams[paramName] = vectorBlob\n\n\t\t\tif vectorExpr.Method != \"\" {\n\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}","sourceCodeStart":3871,"sourceCodeEnd":3907,"githubUrl":"https://github.com/go-redis/redis/blob/36d97525cd8076aed67cddf54778e9ea84550929/search_commands.go#L3871-L3907","documentation":"Error \"FT.HYBRID: SHARD_K_RATIO requires KNN method\" thrown in go-redis/redis.","triggerScenarios":"Thrown at search_commands.go:3889 when the library encounters an invalid state.","commonSituations":"Couple SHARD_K_RATIO with the KNN method in a single options constructor.","solutions":["Remove SHARD_K_RATIO or switch the vector search method to KNN","Set the method explicitly to KNN when using SHARD_K_RATIO"],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"analyzedSha":"36d97525cd8076aed67cddf54778e9ea84550929","analyzedAt":"2026-08-06T01:08:27.376Z","schemaVersion":2}