redis/go-redis · error

FT.HYBRID: SHARD_K_RATIO requires KNN method

Error message

FT.HYBRID: SHARD_K_RATIO requires KNN method

What it means

ShardKRatio is a Redis 8.8+ cluster-only FT.HYBRID option that only applies when the KNN search method is used. The client validates that when ShardKRatio > 0 the vector expression's Method is "KNN", and fails the command otherwise.

Source

Thrown at search_commands.go:3915

			}
			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 c5cad058c7)

Solutions

1. Set Method: "KNN" on the vector expression when using ShardKRatio.
2. Set ShardKRatio to 0 (unset) if you don't need the option.
3. Keep ShardKRatio within 0.1–1.0 and only enable it on Redis 8.8+ clusters.

Example fix

// before
vecOpts := redis.HybridVectorOptions{Method: "", ShardKRatio: 0.5, ...}
// after
vecOpts := redis.HybridVectorOptions{Method: "KNN", ShardKRatio: 0.5, ...}

if vecOpts.ShardKRatio > 0 && vecOpts.Method != "KNN" {
    return errors.New("ShardKRatio requires Method \"KNN\"")
}

func shardKRatioValid(o redis.HybridVectorOptions) bool {
    return o.ShardKRatio == 0 || (o.Method == "KNN" && o.ShardKRatio >= 0.1 && o.ShardKRatio <= 1.0)
}

cmd := client.FTHybridWithArgs(ctx, "idx", opts)
if err := cmd.Err(); err != nil && strings.Contains(err.Error(), "SHARD_K_RATIO requires KNN") {
    // unset ShardKRatio or switch Method to "KNN" and retry
}

When it happens

Trigger: Calling FTHybridWithArgs with a HybridVectorOptions where ShardKRatio is set to a positive value while Method is not "KNN" (e.g. empty or another method name).

Common situations: Setting cluster sharding tuning options copied from an example while using a non-KNN method; leaving ShardKRatio set from a previous query configuration while switching methods.

Related errors

• FT.HYBRID: vector data is required
• FT.HYBRID: vector blob is required
• FT.HYBRID: unsupported vector type %T
• FT.HYBRID: vector Value must contain a blob at index 1
• FT.AGGREGATE: SortByMax must follow a SortBy step

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/4cf8d3db6c8ffd9f. Report an issue: GitHub.