vitessio/vitess · error

initTablet failed because existing tablet keyspace and shard

Error message

initTablet failed because existing tablet keyspace and shard %v/%v differ from the provided ones %v/%v

What it means

initTablet refuses to start a tablet whose existing topo record belongs to a different keyspace/shard than the ones supplied at startup. Vitess checks this sanity invariant to prevent a tablet from silently joining the wrong shard, which would corrupt routing and replication topology. It is thrown when the pre-existing Tablet record in the topo server conflicts with the --keyspace/--shard flags.

Source

Thrown at go/vt/vttablet/tabletmanager/tm_init.go:957

}

func (tm *TabletManager) initTablet(ctx context.Context) error {
	tablet := tm.Tablet()
	err := tm.TopoServer.CreateTablet(ctx, tablet)
	switch {
	case err == nil:
		// It worked, we're good.
	case topo.IsErrType(err, topo.NodeExists):
		// The node already exists, will just try to update
		// it. So we read it first.
		oldTablet, err := tm.TopoServer.GetTablet(ctx, tablet.Alias)
		if err != nil {
			return vterrors.Wrap(err, "initTablet failed to read existing tablet record")
		}

		// Sanity check the keyspace and shard
		if oldTablet.Keyspace != tablet.Keyspace || oldTablet.Shard != tablet.Shard {
			return fmt.Errorf("initTablet failed because existing tablet keyspace and shard %v/%v differ from the provided ones %v/%v", oldTablet.Keyspace, oldTablet.Shard, tablet.Keyspace, tablet.Shard)
		}

		// Update ShardReplication in any case, to be sure.  This is
		// meant to fix the case when a Tablet record was created, but
		// then the ShardReplication record was not (because for
		// instance of a startup timeout). Upon running this code
		// again, we want to fix ShardReplication.
		if updateErr := topo.UpdateTabletReplicationData(ctx, tm.TopoServer, tablet); updateErr != nil {
			log.Error(fmt.Sprintf("UpdateTabletReplicationData failed for tablet %v: %v", topoproto.TabletAliasString(tablet.Alias), updateErr))
			return vterrors.Wrap(updateErr, "UpdateTabletReplicationData failed")
		}
		log.Info(fmt.Sprintf("Successfully updated tablet replication data for alias: %v", topoproto.TabletAliasString(tablet.Alias)))

		// Then overwrite everything, ignoring version mismatch.
		if err := tm.TopoServer.UpdateTablet(ctx, topo.NewTabletInfo(tablet, nil)); err != nil {
			return vterrors.Wrap(err, "UpdateTablet failed")
		}
	default:

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the keyspace/shard passed to the tablet process (flags or init params) match the intended topology
2. Check the existing tablet record: vtctldclient GetTablet <alias> and confirm its keyspace/shard
3. If the old record is stale, delete it with vtctldclient DeleteTablet <alias> and restart the tablet
4. If the flags are wrong, correct the deployment config (e.g. vttablet --keyspace/--shard or the operator's spec) and restart

Example fix

// before (tablet flags wrong for the shard)
vttablet --init_keyspace=commerce --init_shard=0 ...
// after (match the existing topo record, or first delete the stale record)
vtctldclient DeleteTablet zone1-0000000100
vttablet --init_keyspace=commerce --init_shard=1 ...

tablet, err := topo.GetTablet(ctx, alias)
if err == nil && (tablet.Keyspace != wantKeyspace || tablet.Shard != wantShard) {
    // stale record: delete or realign before starting
    topo.DeleteTablet(ctx, alias)
}

if err != nil && strings.Contains(err.Error(), "differ from the provided ones") {
    // inspect and reconcile keyspace/shard before retrying
}

When it happens

Trigger: Calling vttablet Start (initTablet) when a Tablet record for the alias already exists in the topo with different Keyspace or Shard than the provided flags; e.g. re-pointing a tablet to another shard without deleting its old topo record.

Common situations: Operator moved a tablet between shards with vtctldclient but left a stale record; wrong --keyspace/--shard flags in the tablet's init config after a clone or restore; Kubernetes vttablet pod reusing a persistent alias with old metadata; disaster-recovery re-init with copied configs.

Related errors

• not allowed: deny-all security-policy enforced
• not allowed: read-only security-policy enforced
• invalid choice for enum
• value must be either a float64 (interpreted as seconds) or a
• flagutil: NewOptionalFlag requires a non-nil parse function

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