redis/go-redis · error

FT.HYBRID: vector blob is required

Error message

FT.HYBRID: vector blob is required

What it means

After resolving the vector to a byte blob, FT.HYBRID requires the blob to be non-empty. hybridVectorBytes rejects empty byte slices so the command is not sent with a zero-length KNN vector.

Source

Thrown at search_commands.go:3812

		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:
		values := v.Value()
		if len(values) < 2 {
			return nil, fmt.Errorf("FT.HYBRID: vector Value must contain a blob at index 1")
		}
		return values[1], nil
	}
}

func hybridVectorBytes(blob []byte) ([]byte, error) {
	if len(blob) == 0 {
		return nil, fmt.Errorf("FT.HYBRID: vector blob is required")
	}
	return blob, nil
}

// generateVectorParamName returns a parameter name that is not already present
// in params. It is used to pass vector data via the PARAMS mechanism when the
// caller does not provide a VectorParamName, since inline vector blobs are no
// longer supported by Redis.
func generateVectorParamName(params map[string]interface{}) string {
	for i := 0; ; i++ {
		name := fmt.Sprintf("__vector_param_%d", i)
		if _, ok := params[name]; !ok {
			return name
		}
	}
}

// FTHybridWithArgs - Executes a hybrid search with advanced options

View on GitHub (pinned to c5cad058c7)

Solutions

1. Ensure the vector's byte data is populated (len > 0) before calling FTHybrid.
2. Validate the embedding output upstream and fail early with your own error.
3. Check for truncation/serialization bugs that empty the Val slice.

Example fix

// before
vec := &redis.VectorFP32{Val: []float32{}}
// after
if len(embedding) == 0 { return errors.New("empty embedding") }
vec := &redis.VectorFP32{Val: embedding}

if len(vec.Val) == 0 {
    return errors.New("vector blob is empty")
}

func vectorHasData(v *redis.VectorFP32) bool { return v != nil && len(v.Val) > 0 }

cmd := client.FTHybridWithArgs(ctx, "idx", opts)
if err := cmd.Err(); err != nil && strings.Contains(err.Error(), "vector blob is required") {
    // regenerate or re-fetch embeddings before retry
}

When it happens

Trigger: Calling FTHybridWithArgs with a byte-backed vector whose Val is empty (e.g. &redis.VectorFP32{Val: []float32{}}) or a custom Vector whose Value()[1] is an empty []byte.

Common situations: Embedding pipeline returned zero floats on failure; slice truncation bug; deserialized vector struct with nil/empty backing slice.

Related errors

• FT.HYBRID: vector data 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/61ecad0992cdbc99. Report an issue: GitHub.