vitessio/vitess · error

EnsureVSchema(%v) failed: %v

Error message

EnsureVSchema(%v) failed: %v

What it means

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.

Source

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

	mysqld mysqlctl.MysqlDaemon,
	dbcfgs *dbconfigs.DBConfigs,
	schemaDir string,
	kpb *vttestpb.Keyspace,
	ensureDatabase bool,
	uid uint32,
	wr *wrangler.Wrangler,
	srvTopoCounts *stats.CountersWithSingleLabel,
) (uint32, error) {
	keyspace := kpb.Name

	// create a regular keyspace
	if err := ts.CreateKeyspace(ctx, keyspace, &topodatapb.Keyspace{}); err != nil {
		return 0, fmt.Errorf("CreateKeyspace(%v) failed: %v", keyspace, err)
	}

	// make sure a valid vschema has been loaded
	if err := ts.EnsureVSchema(ctx, keyspace); err != nil {
		return 0, fmt.Errorf("EnsureVSchema(%v) failed: %v", keyspace, err)
	}

	// iterate through the shards
	for _, spb := range kpb.Shards {
		shard := spb.Name
		if err := ts.CreateShard(ctx, keyspace, shard); err != nil {
			return 0, fmt.Errorf("CreateShard(%v:%v) failed: %v", keyspace, shard, err)
		}

		for _, cell := range tpb.Cells {
			dbname := spb.DbNameOverride
			if dbname == "" {
				dbname = fmt.Sprintf("vt_%v_%v", keyspace, shard)
			}

			replicas := int(kpb.ReplicaCount)
			if replicas == 0 {
				// 2 replicas in order to ensure the primary cell has a primary and a replica

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Inspect the keyspace's VSchema (vtctldclient GetVSchema <ks>) and fix invalid JSON/structure, then retry.
2. Verify topo write health; retry CreateKs after topo recovers.
3. If the vschema is not needed yet, ensure an empty-but-valid vschema ({}) is written for the keyspace.

Example fix

// before (invalid vschema stored)
{"sharded": true} // missing vindexes for routed tables
// after
{"sharded": true, "vindexes": {...}, "tables": {...}}

// Go: validate the vschema JSON before EnsureVSchema runs
var vs map[string]any
if err := json.Unmarshal(vschemaBytes, &vs); err != nil {
    return fmt.Errorf("invalid vschema for keyspace %s: %w", keyspace, err)
}

if _, err := CreateKs(...); err != nil {
    if strings.Contains(err.Error(), "EnsureVSchema") {
        // fetch and fix the keyspace's vschema, then retry
    }
}

When it happens

Trigger: CreateKs on a keyspace whose VSchema record fails topo write or vschema parsing: invalid routing rules, corrupted existing vschema entry, topo write failure.

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

Related errors

• GetVSchema(keyspace = %s): %w
• RebuildVSchemaGraph failed: %v
• CreateKeyspace(%v) failed: %v
• SaveVSchema(%v) = %w
• failed to get source keyspace vschema: %v

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