{"record":{"id":"45c0f32f97cadf19","repo":"vitessio/vitess","slug":"buildkeyspace-v-failed-v","errorCode":null,"errorMessage":"BuildKeyspace(%v) failed: %v","messagePattern":"BuildKeyspace\\((.+?)\\) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtcombo/tablet_map.go","lineNumber":411,"sourceCode":"\t\t\t\t}\n\t\t\t\tuid++\n\t\t\t}\n\t\t}\n\t}\n\n\t// vschema for the keyspace\n\tif schemaDir != \"\" {\n\t\tf := path.Join(schemaDir, keyspace, \"vschema.json\")\n\t\tif _, err := os.Stat(f); err == nil {\n\t\t\t// load the vschema\n\t\t\tformal, err := vindexes.LoadFormalKeyspace(f)\n\t\t\tif err != nil {\n\t\t\t\treturn 0, fmt.Errorf(\"cannot load vschema file %v for keyspace %v: %v\", f, keyspace, err)\n\t\t\t}\n\n\t\t\t_, err = vindexes.BuildKeyspace(formal, wr.SQLParser())\n\t\t\tif err != nil {\n\t\t\t\treturn 0, fmt.Errorf(\"BuildKeyspace(%v) failed: %v\", keyspace, err)\n\t\t\t}\n\t\t\tksvs := &topo.KeyspaceVSchemaInfo{\n\t\t\t\tName:     keyspace,\n\t\t\t\tKeyspace: formal,\n\t\t\t}\n\t\t\tif err := ts.SaveVSchema(ctx, ksvs); err != nil {\n\t\t\t\treturn 0, fmt.Errorf(\"SaveVSchema(%v) failed: %v\", keyspace, err)\n\t\t\t}\n\t\t} else {\n\t\t\tlog.Info(fmt.Sprintf(\"File %v doesn't exist, skipping vschema for keyspace %v\", f, keyspace))\n\t\t}\n\t}\n\n\t// Rebuild the SrvKeyspace object, so we can support\n\t// range-based sharding queries, and export the redirects.\n\tif err := topotools.RebuildKeyspace(ctx, wr.Logger(), wr.TopoServer(), keyspace, nil, false); err != nil {\n\t\treturn 0, fmt.Errorf(\"cannot rebuild %v: %v\", keyspace, err)\n\t}","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtcombo/tablet_map.go#L393-L429","documentation":"After successfully loading the vschema JSON, CreateKs calls vindexes.BuildKeyspace to instantiate the vindex objects referenced by the vschema. This error means the vschema parsed fine but is semantically invalid — a vindex type doesn't exist, parameters are wrong, or a table references a vindex not defined in the keyspace.","triggerScenarios":"CreateKs with a vschema.json referencing an unregistered vindex type (e.g. a custom vindex not linked in), misspelled vindex names in column_vindexes, invalid vindex parameters, or a non-consistent vindex config.","commonSituations":"Using a third-party/custom vindex without registering it in the build; typos like \"hash\" vs \"unicode_loose_md5\"; vschema from docs referring to vindexes removed or renamed in newer Vitess versions.","solutions":["Read the wrapped error — it names the vindex and the semantic problem.","Fix vindex names in vschema.json to match registered types (hash, numeric, lookup*, etc.).","If using a custom vindex, ensure its package is imported/registered in the vtcombo build.","Verify vindex parameters against the vindex type's documented options."],"exampleFix":"// before\n{\"vindexes\": {\"h\": {\"type\": \"hash_v2\"}}, ...}\n// after\n{\"vindexes\": {\"h\": {\"type\": \"hash\"}}, ...}","handlingStrategy":"validation","validationCode":"// validate vindex references before CreateKs\nformal, err := vindexes.LoadFormalKeyspace(vschemaPath)\nif err == nil {\n\tfor name, vi := range formal.Vindexes {\n\t\tif vindexes.NewVIndex(vi.Type, \"\", vi.Params) == nil {\n\t\t\tfmt.Printf(\"unknown vindex type %q for %s\\n\", vi.Type, name)\n\t\t}\n\t}\n}","typeGuard":null,"tryCatchPattern":"err := CreateKs(...)\nif err != nil && strings.Contains(err.Error(), \"BuildKeyspace\") {\n\treturn fmt.Errorf(\"vschema semantically invalid (check vindex types/params): %v\", err)\n}","preventionTips":["Only reference vindex types registered in the build (or register custom vindexes via import)","Cross-check vindex names and parameters against Vitess docs for your version","Test the vschema with vtctldclient ApplyVSchema in a scratch environment first","Avoid copying vschema examples across incompatible Vitess versions"],"tags":["vschema","vindex","configuration"],"backgroundTag":"vschema-build-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}