{"record":{"id":"c9d3824dfeb3a6f6","repo":"vitessio/vitess","slug":"ensurevschema-v-failed-v","errorCode":null,"errorMessage":"EnsureVSchema(%v) failed: %v","messagePattern":"EnsureVSchema\\((.+?)\\) failed: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtcombo/tablet_map.go","lineNumber":332,"sourceCode":"\tmysqld mysqlctl.MysqlDaemon,\n\tdbcfgs *dbconfigs.DBConfigs,\n\tschemaDir string,\n\tkpb *vttestpb.Keyspace,\n\tensureDatabase bool,\n\tuid uint32,\n\twr *wrangler.Wrangler,\n\tsrvTopoCounts *stats.CountersWithSingleLabel,\n) (uint32, error) {\n\tkeyspace := kpb.Name\n\n\t// create a regular keyspace\n\tif err := ts.CreateKeyspace(ctx, keyspace, &topodatapb.Keyspace{}); err != nil {\n\t\treturn 0, fmt.Errorf(\"CreateKeyspace(%v) failed: %v\", keyspace, err)\n\t}\n\n\t// make sure a valid vschema has been loaded\n\tif err := ts.EnsureVSchema(ctx, keyspace); err != nil {\n\t\treturn 0, fmt.Errorf(\"EnsureVSchema(%v) failed: %v\", keyspace, err)\n\t}\n\n\t// iterate through the shards\n\tfor _, spb := range kpb.Shards {\n\t\tshard := spb.Name\n\t\tif err := ts.CreateShard(ctx, keyspace, shard); err != nil {\n\t\t\treturn 0, fmt.Errorf(\"CreateShard(%v:%v) failed: %v\", keyspace, shard, err)\n\t\t}\n\n\t\tfor _, cell := range tpb.Cells {\n\t\t\tdbname := spb.DbNameOverride\n\t\t\tif dbname == \"\" {\n\t\t\t\tdbname = fmt.Sprintf(\"vt_%v_%v\", keyspace, shard)\n\t\t\t}\n\n\t\t\treplicas := int(kpb.ReplicaCount)\n\t\t\tif replicas == 0 {\n\t\t\t\t// 2 replicas in order to ensure the primary cell has a primary and a replica","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtcombo/tablet_map.go#L314-L350","documentation":"CreateKs validates the keyspace's vschema by calling ts.EnsureVSchema; failure is wrapped as 'EnsureVSchema(<keyspace>) failed'. EnsureVSchema writes the keyspace's VSchema entry into the topo and ensures it parses; errors mean the vschema could not be stored or is invalid.","triggerScenarios":"CreateKs on a keyspace whose VSchema record fails topo write or vschema parsing: invalid routing rules, corrupted existing vschema entry, topo write failure.","commonSituations":"Pre-existing invalid vschema in topo for the keyspace; topo outage mid-keyspace-creation; upstream vschema content (e.g. from a shard template) that doesn't parse.","solutions":["Inspect the keyspace's VSchema (vtctldclient GetVSchema <ks>) and fix invalid JSON/structure, then retry.","Verify topo write health; retry CreateKs after topo recovers.","If the vschema is not needed yet, ensure an empty-but-valid vschema ({}) is written for the keyspace."],"exampleFix":"// before (invalid vschema stored)\n{\"sharded\": true} // missing vindexes for routed tables\n// after\n{\"sharded\": true, \"vindexes\": {...}, \"tables\": {...}}","handlingStrategy":"validation","validationCode":"// Go: validate the vschema JSON before EnsureVSchema runs\nvar vs map[string]any\nif err := json.Unmarshal(vschemaBytes, &vs); err != nil {\n    return fmt.Errorf(\"invalid vschema for keyspace %s: %w\", keyspace, err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := CreateKs(...); err != nil {\n    if strings.Contains(err.Error(), \"EnsureVSchema\") {\n        // fetch and fix the keyspace's vschema, then retry\n    }\n}","preventionTips":["Lint vschema JSON in CI before applying it to a keyspace.","Write a minimal valid vschema ({}) at creation time and update it later.","Monitor topo writes so transient failures are retried rather than left half-created."],"tags":["vtcombo","vschema","keyspace","topology"],"backgroundTag":"vschema-rebuild-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}