redis/go-redis · error

FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0

Error message

FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0

What it means

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.

Source

Thrown at search_commands.go:3920

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

		// Add combine/fusion options
		if options.Combine != nil {
			// Build combine parameters
			combineParams := []interface{}{}

View on GitHub (pinned to c5cad058c7)

Solutions

1. Set ShardKRatio to a value in [0.1, 1.0], e.g. options.VectorExpr.ShardKRatio = 0.5
2. Clamp or validate the value before building options: if r < 0.1 { r = 0.1 }; if r > 1.0 { r = 1.0 }
3. Remove ShardKRatio entirely to use the server default

Example fix

// before
opts := &FTHybridOptions{VectorExpr: &FTHybridVectorExpr{Method: "KNN", ShardKRatio: 1.5}}
// after
opts := &FTHybridOptions{VectorExpr: &FTHybridVectorExpr{Method: "KNN", ShardKRatio: 0.5}}

func validShardKRatio(r float64) bool { return r >= 0.1 && r <= 1.0 }
if opts.VectorExpr != nil && opts.VectorExpr.ShardKRatio != 0 && !validShardKRatio(opts.VectorExpr.ShardKRatio) {
    return fmt.Errorf("ShardKRatio %v outside [0.1, 1.0]", opts.VectorExpr.ShardKRatio)
}

cmd := rdb.FTHybrid(ctx, opts, args...)
if err := cmd.Err(); err != nil {
    if strings.Contains(err.Error(), "SHARD_K_RATIO") { /* fix ratio and retry */ }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• FT.HYBRID: ASC and DESC are mutually exclusive
• invalid key type at index %d
• invalid cursor result format
• invalid total_results format
• invalid results format

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