go-redis/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

Error "FT.HYBRID: SHARD_K_RATIO must be between 0.1 and 1.0" thrown in go-redis/redis.

Source

Thrown at search_commands.go:3894

				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 36d97525cd)

Solutions

1. Clamp SHARD_K_RATIO to the [0.1, 1.0] range
2. Validate the ratio value before building the query

When it happens

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

Common situations: Range-check ratio parameters at option construction.

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