go-redis/redis · error

FT.CREATE: SCHEMA FieldType VECTOR is required for VectorArg

Error message

FT.CREATE: SCHEMA FieldType VECTOR is required for VectorArgs

What it means

Returned by FTCreate when VectorArgs is non-nil but the FieldSchema.FieldType is not SearchFieldType. Only a VECTOR field carries vector index options (FLAT/HNSW/Vamana); attaching VectorArgs to a TEXT/NUMERIC/TAG field is contradictory. The guard is at search_commands.go:1464.

Source

Thrown at search_commands.go:1466

		cmd.SetErr(fmt.Errorf("FT.CREATE: SCHEMA is required"))
		return cmd
	}
	args = append(args, "SCHEMA")
	for _, schema := range schema {
		if schema.FieldName == "" || schema.FieldType == SearchFieldTypeInvalid {
			cmd := NewStatusCmd(ctx, args...)
			cmd.SetErr(fmt.Errorf("FT.CREATE: SCHEMA FieldName and FieldType are required"))
			return cmd
		}
		args = append(args, schema.FieldName)
		if schema.As != "" {
			args = append(args, "AS", schema.As)
		}
		args = append(args, schema.FieldType.String())
		if schema.VectorArgs != nil {
			if schema.FieldType != SearchFieldTypeVector {
				cmd := NewStatusCmd(ctx, args...)
				cmd.SetErr(fmt.Errorf("FT.CREATE: SCHEMA FieldType VECTOR is required for VectorArgs"))
				return cmd
			}
			// Check mutual exclusivity of vector options
			optionCount := 0
			if schema.VectorArgs.FlatOptions != nil {
				optionCount++
			}
			if schema.VectorArgs.HNSWOptions != nil {
				optionCount++
			}
			if schema.VectorArgs.VamanaOptions != nil {
				optionCount++
			}
			if optionCount != 1 {
				cmd := NewStatusCmd(ctx, args...)
				cmd.SetErr(fmt.Errorf("FT.CREATE: SCHEMA VectorArgs must have exactly one of FlatOptions, HNSWOptions, or VamanaOptions"))
				return cmd
			}

View on GitHub (pinned to 36d97525cd)

Solutions

1. Set FieldType: redis.SearchFieldTypeVector on any FieldSchema that also sets VectorArgs.
2. Centralize vector-field construction in a helper that always sets both together.
3. Add a unit test asserting every FieldSchema with VectorArgs has FieldType == SearchFieldTypeVector.

Example fix

// before
&redis.FieldSchema{FieldName: "v", FieldType: redis.SearchFieldTypeText, VectorArgs: vec}

// after
&redis.FieldSchema{FieldName: "v", FieldType: redis.SearchFieldTypeVector, VectorArgs: vec}

if f.VectorArgs != nil && f.FieldType != redis.SearchFieldTypeVector {
    return fmt.Errorf("field %q: VectorArgs requires FieldType=VECTOR", f.FieldName)
}

func vectorArgsConsistent(f *redis.FieldSchema) bool {
    if f.VectorArgs == nil {
        return true
    }
    return f.FieldType == redis.SearchFieldTypeVector
}

When it happens

Trigger: Setting schema.VectorArgs on a FieldSchema whose FieldType was left as the default or explicitly set to a non-VECTOR type. Common when reusing a FieldSchema template for multiple field kinds.

Common situations: Copy-pasting a text field schema and adding VectorArgs without changing FieldType, or building a field map where the type key and vector options come from different sources that disagree.

Related errors

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

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