go-redis/redis · error

FT.CREATE: Type, Dim and DistanceMetric are required for VEC

Error message

FT.CREATE: Type, Dim and DistanceMetric are required for VECTOR HNSW

What it means

Returned by FTCreate when HNSWOptions is selected but Type, Dim, or DistanceMetric is unset. These three are mandatory for a VECTOR HNSW index; tuning knobs (M, EF_CONSTRUCTION, etc.) are optional. The guard is at search_commands.go:1508.

Source

Thrown at search_commands.go:1510

				flatArgs := []interface{}{
					"TYPE", schema.VectorArgs.FlatOptions.Type,
					"DIM", schema.VectorArgs.FlatOptions.Dim,
					"DISTANCE_METRIC", schema.VectorArgs.FlatOptions.DistanceMetric,
				}
				if schema.VectorArgs.FlatOptions.InitialCapacity > 0 {
					flatArgs = append(flatArgs, "INITIAL_CAP", schema.VectorArgs.FlatOptions.InitialCapacity)
				}
				if schema.VectorArgs.FlatOptions.BlockSize > 0 {
					flatArgs = append(flatArgs, "BLOCK_SIZE", schema.VectorArgs.FlatOptions.BlockSize)
				}
				args = append(args, len(flatArgs))
				args = append(args, flatArgs...)
			}
			if schema.VectorArgs.HNSWOptions != nil {
				args = append(args, "HNSW")
				if schema.VectorArgs.HNSWOptions.Type == "" || schema.VectorArgs.HNSWOptions.Dim == 0 || schema.VectorArgs.HNSWOptions.DistanceMetric == "" {
					cmd := NewStatusCmd(ctx, args...)
					cmd.SetErr(fmt.Errorf("FT.CREATE: Type, Dim and DistanceMetric are required for VECTOR HNSW"))
					return cmd
				}
				hnswArgs := []interface{}{
					"TYPE", schema.VectorArgs.HNSWOptions.Type,
					"DIM", schema.VectorArgs.HNSWOptions.Dim,
					"DISTANCE_METRIC", schema.VectorArgs.HNSWOptions.DistanceMetric,
				}
				if schema.VectorArgs.HNSWOptions.InitialCapacity > 0 {
					hnswArgs = append(hnswArgs, "INITIAL_CAP", schema.VectorArgs.HNSWOptions.InitialCapacity)
				}
				if schema.VectorArgs.HNSWOptions.MaxEdgesPerNode > 0 {
					hnswArgs = append(hnswArgs, "M", schema.VectorArgs.HNSWOptions.MaxEdgesPerNode)
				}
				if schema.VectorArgs.HNSWOptions.MaxAllowedEdgesPerNode > 0 {
					hnswArgs = append(hnswArgs, "EF_CONSTRUCTION", schema.VectorArgs.HNSWOptions.MaxAllowedEdgesPerNode)
				}
				if schema.VectorArgs.HNSWOptions.EFRunTime > 0 {
					hnswArgs = append(hnswArgs, "EF_RUNTIME", schema.VectorArgs.HNSWOptions.EFRunTime)

View on GitHub (pinned to 36d97525cd)

Solutions

1. Set HNSWOptions.Type, HNSWOptions.Dim (>0), and HNSWOptions.DistanceMetric on every HNSW vector field.
2. Keep a shared helper that returns a fully-populated HNSW options struct given (dim, metric).
3. Assert Dim matches your embedding dimensionality at startup.

Example fix

// before
&redis.FTHNSWOptions{Type: "FLOAT32", MaxEdgesPerNode: 16}

// after
&redis.FTHNSWOptions{Type: "FLOAT32", Dim: 768, DistanceMetric: "COSINE", MaxEdgesPerNode: 16}

o := f.VectorArgs.HNSWOptions
if o.Type == "" || o.Dim == 0 || o.DistanceMetric == "" {
    return fmt.Errorf("HNSW vector field %q needs Type, Dim>0, DistanceMetric", f.FieldName)
}

When it happens

Trigger: Constructing &redis.FTHNSWOptions{} missing Type, Dim (==0), or DistanceMetric (==""). Often only the tuning parameters are set while the required trio is overlooked.

Common situations: Copy-pasting an HNSW config that sets M and EF_RUNTIME but not the base triplet, or deriving Dim from an embedding library whose value is 0 before model load.

Related errors

• FT.CREATE: SCHEMA FieldType VECTOR is required for VectorArg
• FT.CREATE: SCHEMA VectorArgs must have exactly one of FlatOp
• FT.CREATE: Type, Dim and DistanceMetric are required for VEC
• FT.CREATE: Type, Dim and DistanceMetric are required for VEC
• FT.CREATE: SCHEMA is required

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