keyspace(%s) doesn't exist, check if the keyspace is initial

Error message

keyspace(%s) doesn't exist, check if the keyspace is initialized

What it means

Before updating the VSchema, the command checks that the target keyspace exists in the topo via GetKeyspace. If the topo reports the node does not exist ('node doesn't exist'), this friendlier error is returned. It prevents creating VSchema entries for keyspaces that were never initialized.

Source

Thrown at go/vt/vtctl/vtctl.go:3444

	}
	sort.Strings(vdxNames)
	for _, name := range vdxNames {
		vdx := ksVs.Vindexes[name]
		if val, ok := vdx.(vindexes.ParamValidating); ok {
			for _, param := range val.UnknownParams() {
				wr.Logger().Warningf("Unknown parameter in vindex %s: %s", name, param)
			}
		}
	}

	if *dryRun {
		wr.Logger().Printf("Dry run: Skipping update of VSchema\n")
		return nil
	}

	if _, err := wr.TopoServer().GetKeyspace(ctx, keyspace); err != nil {
		if strings.Contains(err.Error(), "node doesn't exist") {
			return fmt.Errorf("keyspace(%s) doesn't exist, check if the keyspace is initialized", keyspace)
		}
		return err
	}

	if _, err := vindexes.BuildKeyspace(ksvs.Keyspace, wr.SQLParser()); err != nil {
		return err
	}

	if err := wr.TopoServer().SaveVSchema(ctx, ksvs); err != nil {
		return err
	}

	if *skipRebuild {
		wr.Logger().Warningf("Skipping rebuild of SrvVSchema, will need to run RebuildVSchemaGraph for changes to take effect")
		return nil
	}
	return wr.TopoServer().RebuildSrvVSchema(ctx, cells)
}

View on GitHub (pinned to 01a25a7d17)

Solutions

Verify the keyspace exists: `vtctldclient GetKeyspace <name>` or `vtctl GetTablets`
Initialize the keyspace first (create tablets/etcd record) or use `vtctldclient CreateKeyspace`
Check you are pointed at the correct topo server/cell (--topo flags, VTCTLD_TOPO_INFO)

Example fix

// before
vtctldclient ApplyVSchema --vschema vs.json commerce
// after
vtctldclient GetKeyspace commerce  # confirm exists first
vtctldclient ApplyVSchema --vschema vs.json commerce

Defensive patterns

Strategy: validation

Validate before calling

_, err := wr.TopoServer().GetKeyspace(ctx, keyspace)
if err != nil {
	return fmt.Errorf("keyspace %s must exist before ApplyVSchema: %v", keyspace, err)
}

Try / catch

if err := client.ApplyVSchema(ctx, ks, vs); err != nil {
	if strings.Contains(err.Error(), "doesn't exist") {
		return fmt.Errorf("initialize keyspace %s first", ks)
	}
	return err
}

Prevention

Always run GetKeyspace to confirm existence before applying vschema changes
Verify topo server endpoints/environment before operations
Standardize keyspace names in config to avoid typos

When it happens

Trigger: Running `vtctldclient ApplyVSchema`/RebuildKeyspace against a keyspace name that has no keyspace record in the topo server.

Common situations: Typo in keyspace name; keyspace created only implicitly by tablets before any GetKeyspace/init; fresh cluster where no keyspace object was created yet; wrong topo environment (staging vs prod).

Related errors

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