redis/go-redis · error

FT.HYBRID: vector data is required

Error message

FT.HYBRID: vector data is required

What it means

FTHybrid requires actual vector data for the KNN query. hybridVectorBlob receives the Vector argument and returns this error when it is nil, failing the command before anything is sent to Redis.

Source

Thrown at search_commands.go:3783

// The 'index' parameter specifies the index to search, 'searchExpr' is the search query,
// 'vectorField' is the name of the vector field, and 'vectorData' is the vector to search with.
// FTHybrid is still experimental, the command behaviour and signature may change
func (c cmdable) FTHybrid(ctx context.Context, index string, searchExpr string, vectorField string, vectorData Vector) *FTHybridCmd {
	options := &FTHybridOptions{
		CountExpressions: 2,
		SearchExpressions: []FTHybridSearchExpression{
			{Query: searchExpr},
		},
		VectorExpressions: []FTHybridVectorExpression{
			{VectorField: vectorField, VectorData: vectorData},
		},
	}
	return c.FTHybridWithArgs(ctx, index, options)
}

func hybridVectorBlob(v Vector) (interface{}, error) {
	if v == nil {
		return nil, fmt.Errorf("FT.HYBRID: vector data is required")
	}

	switch vector := v.(type) {
	case *VectorFP32:
		return hybridVectorBytes(vector.Val)
	case *VectorFloat16:
		return hybridVectorBytes(vector.Val)
	case *VectorBFloat16:
		return hybridVectorBytes(vector.Val)
	case *VectorFloat64:
		return hybridVectorBytes(vector.Val)
	case *VectorInt8:
		return hybridVectorBytes(vector.Val)
	case *VectorUint8:
		return hybridVectorBytes(vector.Val)
	case *VectorValues, *VectorRef:
		return nil, fmt.Errorf("FT.HYBRID: unsupported vector type %T", v)
	default:

View on GitHub (pinned to c5cad058c7)

Solutions

1. Provide a non-nil vector (e.g. &redis.VectorFP32{Val: ...} or a Vector built from floats).
2. Check the code path that produces your embeddings for nil returns before calling FTHybrid.
3. If you intend to reference a stored vector instead, use VectorRef rather than a nil data vector.

Example fix

// before
opts := redis.FTHybridOptions{Vector: nil}
// after
opts := redis.FTHybridOptions{Vector: &redis.VectorFP32{Val: []float32{0.1, 0.2, 0.3}}}

if opts.Vector == nil {
    return errors.New("FT.HYBRID: provide a non-nil vector")
}

func hasVector(v redis.Vector) bool { return v != nil }

cmd := client.FTHybridWithArgs(ctx, "idx", opts)
if err := cmd.Err(); err != nil && strings.Contains(err.Error(), "vector data is required") {
    // regenerate embeddings and rebuild options
}

When it happens

Trigger: Calling FTHybridWithArgs (or FTHybrid) with VectorData set to nil in the HybridVectorOptions / vector expression.

Common situations: Building query options dynamically where the embedding generation step failed and left the vector nil; copying struct fields and dropping the vector; JSON-unmarshaled options that omitted the field.

Related errors

• FT.HYBRID: vector blob is required
• FT.HYBRID: SHARD_K_RATIO requires KNN method
• 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/6cfe64ae4bc7772c. Report an issue: GitHub.