vitessio/vitess · error

cannot load vschema file %v for keyspace %v: %v

Error message

cannot load vschema file %v for keyspace %v: %v

What it means

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.

Source

Thrown at go/vt/vtcombo/tablet_map.go:406

			for i := 0; i < rdonlys; i++ {
				// create a rdonly tablet
				if err := CreateTablet(ctx, env, ts, cell, uid, keyspace, shard, dbname, topodatapb.TabletType_RDONLY, mysqld, dbcfgs.Clone(), srvTopoCounts); err != nil {
					return 0, err
				}
				uid++
			}
		}
	}

	// vschema for the keyspace
	if schemaDir != "" {
		f := path.Join(schemaDir, keyspace, "vschema.json")
		if _, err := os.Stat(f); err == nil {
			// load the vschema
			formal, err := vindexes.LoadFormalKeyspace(f)
			if err != nil {
				return 0, fmt.Errorf("cannot load vschema file %v for keyspace %v: %v", f, keyspace, err)
			}

			_, err = vindexes.BuildKeyspace(formal, wr.SQLParser())
			if err != nil {
				return 0, fmt.Errorf("BuildKeyspace(%v) failed: %v", keyspace, err)
			}
			ksvs := &topo.KeyspaceVSchemaInfo{
				Name:     keyspace,
				Keyspace: formal,
			}
			if err := ts.SaveVSchema(ctx, ksvs); err != nil {
				return 0, fmt.Errorf("SaveVSchema(%v) failed: %v", keyspace, err)
			}
		} else {
			log.Info(fmt.Sprintf("File %v doesn't exist, skipping vschema for keyspace %v", f, keyspace))
		}
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Validate the vschema JSON with `vtctldclient ApplyVSchema` against a dry run, or run it through json decode locally.
2. Fix JSON syntax errors reported by the wrapped err (line/column info is usually included).
3. Ensure the file matches the FormalKeyspace format (sharded keyspaces need vindexes and column VIndex entries).
4. Check that vschema.json corresponds to the current Vitess version's expected format.
5. If no vschema is needed, delete the file — vtcombo skips keyspaces without vschema.json.

Example fix

// before: malformed vschema.json
{"tables": {"t": {"column_vindexes": [}}
// after
{"sharded": true, "vindexes": {}, "tables": {"t": {}}}

// validate vschema.json parses before calling CreateKs
f := path.Join(schemaDir, keyspace, "vschema.json")
data, err := os.ReadFile(f)
if err == nil {
	var formal vsvpb.Keyspace
	if err := protojson.Unmarshal(data, &formal); err != nil {
		return fmt.Errorf("invalid vschema %s: %v", f, err)
	}
}

err := CreateKs(...)
if err != nil && strings.Contains(err.Error(), "cannot load vschema file") {
	return fmt.Errorf("fix vschema.json syntax for keyspace: %v", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error parsing the json file : %v
• %w: unable to parse JSON of load flags
• BuildKeyspace(%v) failed: %v
• region_bytes must be 1 or 2: %v
• vindexType %q not found

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/ab2ab0c61b60c020. Report an issue: GitHub.