go-redis/redis · error

FT.HYBRID: SHARD_K_RATIO requires KNN method

Error message

FT.HYBRID: SHARD_K_RATIO requires KNN method

What it means

Error "FT.HYBRID: SHARD_K_RATIO requires KNN method" thrown in go-redis/redis.

Source

Thrown at search_commands.go:3889

			}
			args = append(args, "$"+paramName)
			params[paramName] = vectorBlob

			if vectorExpr.Method != "" {
				args = append(args, vectorExpr.Method)
				if len(vectorExpr.MethodParams) > 0 {
					// MethodParams should be key-value pairs, count them
					args = append(args, len(vectorExpr.MethodParams))
					args = append(args, vectorExpr.MethodParams...)
				}
			}

			// SHARD_K_RATIO applies to the KNN method only (Redis 8.8+, cluster only).
			// Zero means "unset" and falls back to the server default of 1.0.
			if vectorExpr.ShardKRatio > 0 {
				if vectorExpr.Method != "KNN" {
					cmd := newFTHybridCmd(ctx, options, args...)
					cmd.SetErr(fmt.Errorf("FT.HYBRID: SHARD_K_RATIO requires KNN method"))
					return cmd
				}
				if vectorExpr.ShardKRatio < 0.1 || vectorExpr.ShardKRatio > 1.0 {
					cmd := newFTHybridCmd(ctx, options, args...)
					cmd.SetErr(fmt.Errorf("FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0"))
					return cmd
				}
				args = append(args, "SHARD_K_RATIO", vectorExpr.ShardKRatio)
			}

			if vectorExpr.Filter != "" {
				args = append(args, "FILTER", vectorExpr.Filter)
			}

			if vectorExpr.YieldScoreAs != "" {
				args = append(args, "YIELD_SCORE_AS", vectorExpr.YieldScoreAs)
			}
		}

View on GitHub (pinned to 36d97525cd)

Solutions

1. Remove SHARD_K_RATIO or switch the vector search method to KNN
2. Set the method explicitly to KNN when using SHARD_K_RATIO

When it happens

Trigger: Thrown at search_commands.go:3889 when the library encounters an invalid state.

Common situations: Couple SHARD_K_RATIO with the KNN method in a single options constructor.

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/8fe2040344b7ee7e.json. Report an issue: GitHub.