redis/go-redis · error

FT.HYBRID: unsupported vector type %T

Error message

FT.HYBRID: unsupported vector type %T

What it means

The FTHybrid vector blob builder only accepts byte-backed vector types (*VectorFP32, *VectorFloat16, *VectorInt8, *VectorUint8) or any custom type exposing Value() with a blob at index 1. Passing a symbolic/vector-first type like *VectorValues or *VectorRef is rejected because FT.HYBRID's KNN input must be raw bytes.

Source

Thrown at search_commands.go:3800

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

View on GitHub (pinned to c5cad058c7)

Solutions

1. Use a byte-backed type such as *VectorFP32 (or *VectorFloat16/*VectorInt8/*VectorUint8).
2. If you have floats, wrap them in a blob-carrying vector instead of VectorValues.
3. Implement a custom Vector whose Value() returns [name, blob] with the binary data at index 1.

Example fix

// before
vec := &redis.VectorValues{Val: []float64{0.1, 0.2}}
// after
vec := &redis.VectorFP32{Val: []float32{0.1, 0.2}}

switch v.(type) {
case *redis.VectorValues, *redis.VectorRef:
    return errors.New("FT.HYBRID needs a blob-backed vector, not VectorValues/VectorRef")
}

func isBlobVector(v redis.Vector) bool {
    switch v.(type) {
    case *redis.VectorFP32, *redis.VectorFloat16, *redis.VectorInt8, *redis.VectorUint8:
        return true
    default:
        return false
    }
}

cmd := client.FTHybridWithArgs(ctx, "idx", opts)
if err := cmd.Err(); err != nil && strings.Contains(err.Error(), "unsupported vector type") {
    // swap the vector implementation and retry once
}

When it happens

Trigger: Calling FTHybridWithArgs with Vector set to &redis.VectorValues{...} or &redis.VectorRef{...}, or an unsupported Vector implementation.

Common situations: Reusing a vector type created for FT.KNN search options in FT.HYBRID; confusing reference-style vectors (pointing at stored/embedded data) with inline blob vectors.

Related errors

• FT.HYBRID: vector data is required
• FT.HYBRID: vector Value must contain a blob at index 1
• FT.HYBRID: vector blob is required
• FT.HYBRID: SHARD_K_RATIO requires KNN method
• unexpected type %T, want map or key/value array

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