{"id":"c253d5b657330c36","repo":"go-redis/redis","slug":"ft-create-schema-vectorargs-must-have-exactly-one","errorCode":null,"errorMessage":"FT.CREATE: SCHEMA VectorArgs must have exactly one of FlatOptions, HNSWOptions, or VamanaOptions","messagePattern":"FT\\.CREATE: SCHEMA VectorArgs must have exactly one of FlatOptions, HNSWOptions, or VamanaOptions","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"search_commands.go","lineNumber":1482,"sourceCode":"\t\t\tif schema.FieldType != SearchFieldTypeVector {\n\t\t\t\tcmd := NewStatusCmd(ctx, args...)\n\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.CREATE: SCHEMA FieldType VECTOR is required for VectorArgs\"))\n\t\t\t\treturn cmd\n\t\t\t}\n\t\t\t// Check mutual exclusivity of vector options\n\t\t\toptionCount := 0\n\t\t\tif schema.VectorArgs.FlatOptions != nil {\n\t\t\t\toptionCount++\n\t\t\t}\n\t\t\tif schema.VectorArgs.HNSWOptions != nil {\n\t\t\t\toptionCount++\n\t\t\t}\n\t\t\tif schema.VectorArgs.VamanaOptions != nil {\n\t\t\t\toptionCount++\n\t\t\t}\n\t\t\tif optionCount != 1 {\n\t\t\t\tcmd := NewStatusCmd(ctx, args...)\n\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.CREATE: SCHEMA VectorArgs must have exactly one of FlatOptions, HNSWOptions, or VamanaOptions\"))\n\t\t\t\treturn cmd\n\t\t\t}\n\t\t\tif schema.VectorArgs.FlatOptions != nil {\n\t\t\t\targs = append(args, \"FLAT\")\n\t\t\t\tif schema.VectorArgs.FlatOptions.Type == \"\" || schema.VectorArgs.FlatOptions.Dim == 0 || schema.VectorArgs.FlatOptions.DistanceMetric == \"\" {\n\t\t\t\t\tcmd := NewStatusCmd(ctx, args...)\n\t\t\t\t\tcmd.SetErr(fmt.Errorf(\"FT.CREATE: Type, Dim and DistanceMetric are required for VECTOR FLAT\"))\n\t\t\t\t\treturn cmd\n\t\t\t\t}\n\t\t\t\tflatArgs := []interface{}{\n\t\t\t\t\t\"TYPE\", schema.VectorArgs.FlatOptions.Type,\n\t\t\t\t\t\"DIM\", schema.VectorArgs.FlatOptions.Dim,\n\t\t\t\t\t\"DISTANCE_METRIC\", schema.VectorArgs.FlatOptions.DistanceMetric,\n\t\t\t\t}\n\t\t\t\tif schema.VectorArgs.FlatOptions.InitialCapacity > 0 {\n\t\t\t\t\tflatArgs = append(flatArgs, \"INITIAL_CAP\", schema.VectorArgs.FlatOptions.InitialCapacity)\n\t\t\t\t}\n\t\t\t\tif schema.VectorArgs.FlatOptions.BlockSize > 0 {","sourceCodeStart":1464,"sourceCodeEnd":1500,"githubUrl":"https://github.com/go-redis/redis/blob/36d97525cd8076aed67cddf54778e9ea84550929/search_commands.go#L1464-L1500","documentation":"Returned by FTCreate when FTVectorArgs does not have exactly one of FlatOptions, HNSWOptions, or VamanaOptions set. RediSearch requires a single vector algorithm choice; setting zero (no algorithm) or more than one (ambiguous) is rejected client-side at search_commands.go:1480.","triggerScenarios":"Constructing FTVectorArgs{} with no options set, or populating two option structs (e.g. FlatOptions and HNSWOptions) simultaneously. The optionCount counter at line 1470 must equal exactly 1.","commonSituations":"Conditionally building options where a switch falls through leaving none set, or merging configs that accidentally set multiple algorithm options. Also happens when migrating between algorithms and forgetting to nil the old field.","solutions":["Set exactly one of FlatOptions, HNSWOptions, or VamanaOptions on FTVectorArgs.","Reset the unused algorithm pointers to nil when switching algorithms at runtime.","Use a builder/switch that assigns one option struct and leaves the others nil."],"exampleFix":"// before (two set)\n&redis.FTVectorArgs{FlatOptions: f, HNSWOptions: h}\n\n// after (exactly one)\n&redis.FTVectorArgs{HNSWOptions: h}","handlingStrategy":"validation","validationCode":"func countVecOpts(v *redis.FTVectorArgs) int {\n    n := 0\n    if v.FlatOptions != nil { n++ }\n    if v.HNSWOptions != nil { n++ }\n    if v.VamanaOptions != nil { n++ }\n    return n\n}\nif n := countVecOpts(f.VectorArgs); n != 1 {\n    return fmt.Errorf(\"exactly one vector algorithm required, got %d\", n)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Assign exactly one of Flat/HNSW/Vamana; nil the others when switching.","Build vector options through a switch that sets only the chosen algorithm.","Add an assertion in tests that optionCount==1 for every vector field."],"tags":["redisearch","ft-create","vector","schema","mutual-exclusion","validation"],"analyzedSha":"36d97525cd8076aed67cddf54778e9ea84550929","analyzedAt":"2026-08-06T01:08:27.376Z","schemaVersion":2}