{"record":{"id":"ab2ab0c61b60c020","repo":"vitessio/vitess","slug":"cannot-load-vschema-file-v-for-keyspace-v-v","errorCode":null,"errorMessage":"cannot load vschema file %v for keyspace %v: %v","messagePattern":"cannot load vschema file (.+?) for keyspace (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtcombo/tablet_map.go","lineNumber":406,"sourceCode":"\n\t\t\tfor i := 0; i < rdonlys; i++ {\n\t\t\t\t// create a rdonly tablet\n\t\t\t\tif err := CreateTablet(ctx, env, ts, cell, uid, keyspace, shard, dbname, topodatapb.TabletType_RDONLY, mysqld, dbcfgs.Clone(), srvTopoCounts); err != nil {\n\t\t\t\t\treturn 0, err\n\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","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtcombo/tablet_map.go#L388-L424","documentation":"If a schemaDir is configured, CreateKs looks for <schemaDir>/<keyspace>/vschema.json and, when the file exists, loads it with vindexes.LoadFormalKeyspace. This error wraps any parse/validation failure of that vschema JSON file — the file exists but is not valid JSON or not a valid FormalKeyspace structure.","triggerScenarios":"Calling CreateKs when schemaDir is set and the keyspace's vschema.json exists but contains malformed JSON, an unexpected schema (e.g. plain tables list instead of formal vschema format), or unknown vindex types.","commonSituations":"Hand-edited vschema.json with a syntax error; vschema copied from a different Vitess version using an outdated format; stale file left over from a previous test run; confusing the tablet schema file with vschema.json.","solutions":["Validate the vschema JSON with `vtctldclient ApplyVSchema` against a dry run, or run it through json decode locally.","Fix JSON syntax errors reported by the wrapped err (line/column info is usually included).","Ensure the file matches the FormalKeyspace format (sharded keyspaces need vindexes and column VIndex entries).","Check that vschema.json corresponds to the current Vitess version's expected format.","If no vschema is needed, delete the file — vtcombo skips keyspaces without vschema.json."],"exampleFix":"// before: malformed vschema.json\n{\"tables\": {\"t\": {\"column_vindexes\": [}}\n// after\n{\"sharded\": true, \"vindexes\": {}, \"tables\": {\"t\": {}}}","handlingStrategy":"validation","validationCode":"// validate vschema.json parses before calling CreateKs\nf := path.Join(schemaDir, keyspace, \"vschema.json\")\ndata, err := os.ReadFile(f)\nif err == nil {\n\tvar formal vsvpb.Keyspace\n\tif err := protojson.Unmarshal(data, &formal); err != nil {\n\t\treturn fmt.Errorf(\"invalid vschema %s: %v\", f, err)\n\t}\n}","typeGuard":null,"tryCatchPattern":"err := CreateKs(...)\nif err != nil && strings.Contains(err.Error(), \"cannot load vschema file\") {\n\treturn fmt.Errorf(\"fix vschema.json syntax for keyspace: %v\", err)\n}","preventionTips":["Run vschema.json through a JSON linter before deployment","Keep vschema files under version control to catch accidental edits","Use the current Vitess version's vschema format in examples","Delete vschema.json when a keyspace is intentionally unsharded/unmanaged"],"tags":["json","vschema","configuration"],"backgroundTag":"vschema-parse-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}