{"record":{"id":"1c355bf88f62f2a1","repo":"vitessio/vitess","slug":"a-conflicting-vindex-named-v-already-exists-in-th","errorCode":null,"errorMessage":"a conflicting vindex named %v already exists in the target vschema","messagePattern":"a conflicting vindex named (.+?) already exists in the target vschema","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/wrangler/materializer.go","lineNumber":756,"sourceCode":"\t\tfor _, field := range tableSchema.TableDefinitions[0].Fields {\n\t\t\tif sourceVindexColumns[0] == field.Name {\n\t\t\t\ttargetVindexType, err = vindexes.ChooseVindexForType(field.Type)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn nil, nil, nil, err\n\t\t\t\t}\n\t\t\t\ttargetVindex = &vschemapb.Vindex{\n\t\t\t\t\tType: targetVindexType,\n\t\t\t\t}\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t\tif targetVindex == nil {\n\t\t\t// Unreachable. We validated column names when generating the DDL.\n\t\t\treturn nil, nil, nil, fmt.Errorf(\"column %s not found in schema %v\", sourceVindexColumns[0], tableSchema.TableDefinitions[0])\n\t\t}\n\t\tif existing, ok := targetVSchema.Vindexes[targetVindexType]; ok {\n\t\t\tif !proto.Equal(existing, targetVindex) {\n\t\t\t\treturn nil, nil, nil, fmt.Errorf(\"a conflicting vindex named %v already exists in the target vschema\", targetVindexType)\n\t\t\t}\n\t\t} else {\n\t\t\ttargetVSchema.Vindexes[targetVindexType] = targetVindex\n\t\t}\n\n\t\ttargetTable = &vschemapb.Table{\n\t\t\tColumnVindexes: []*vschemapb.ColumnVindex{{\n\t\t\t\tColumn: vindexFromCols[0],\n\t\t\t\tName:   targetVindexType,\n\t\t\t}},\n\t\t}\n\t} else {\n\t\ttargetTable = &vschemapb.Table{}\n\t}\n\tif existing, ok := targetVSchema.Tables[targetTableName]; ok {\n\t\tif !proto.Equal(existing, targetTable) {\n\t\t\treturn nil, nil, nil, fmt.Errorf(\"a conflicting table named %v already exists in the target vschema\", targetTableName)\n\t\t}","sourceCodeStart":738,"sourceCodeEnd":774,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/wrangler/materializer.go#L738-L774","documentation":"When the target keyspace is sharded, Vitess chooses a primary vindex type (hash/binary/unicode hash etc.) for the lookup table and checks whether that type-name already exists in the target vschema's Vindexes map. If an entry with that name exists but with a different definition (proto.Equal fails), creation aborts to avoid overwriting an unrelated vindex.","triggerScenarios":"targetVSchema.Vindexes already contains an entry keyed by the chosen type string (e.g. \"hash\") with different settings than the plain vindex Vitess wants to add — e.g. the operator redefined `hash` with custom params.","commonSituations":"Target vschema has a custom-parameterized vindex named `hash` (or `binary`/`unicode_lo_xx`) from earlier manual config; applying legacy vschema files that name built-in types with extra params.","solutions":["Rename your custom vindex in the target vschema to something other than the built-in type name, or accept the built-in plain definition and update the vschema","Inspect the target vschema (`vtctldclient GetVSchema`) to see the conflicting entry and reconcile it","If the existing definition is obsolete, remove it and retry"],"exampleFix":"// before: custom vindex shadowing the built-in name\n\"vindexes\": {\"hash\": {\"type\": \"hash\", \"params\": {\"hash\": \"xxhash\"}}}\n// after: use a distinct name\n\"vindexes\": {\"xxhash_vdx\": {\"type\": \"hash\", \"params\": {\"hash\": \"xxhash\"}}}","handlingStrategy":"validation","validationCode":"tvs, _ := ts.GetVSchema(ctx, targetKeyspace)\nfor name, v := range tvs.Vindexes {\n    if name == \"hash\" || name == \"binary\" || strings.HasPrefix(name, \"unicode_lo\") {\n        if len(v.Params) > 0 || v.Owner != \"\" {\n            return fmt.Errorf(\"built-in vindex name %s is shadowed with custom params\", name)\n        }\n    }\n}","typeGuard":"func shadowsBuiltInVindex(tvs *vschemapb.Keyspace, typeName string, want *vschemapb.Vindex) bool {\n    existing, ok := tvs.Vindexes[typeName]\n    return ok && !proto.Equal(existing, want)\n}","tryCatchPattern":"if err := createLookupVindex(...); err != nil {\n    if strings.Contains(err.Error(), \"conflicting vindex named\") {\n        return renameCustomVindex(targetKS, typeName) // free the built-in name, retry\n    }\n    return err\n}","preventionTips":["Never name custom/parameterized vindexes after built-in types (hash, binary, unicode_lo_*)","Review target vschema before creating lookup vindexes into sharded keyspaces","Keep built-in vindex definitions plain when the type name is used as the map key"],"tags":["vitess","vschema","vindex","conflict"],"backgroundTag":"vschema-name-conflict","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}