vitessio/vitess · error

old tablet has shard %v/%v. Cannot override with shard %v/%v

Error message

old tablet has shard %v/%v. Cannot override with shard %v/%v. Delete and re-add tablet if you want to change the tablet's keyspace/shard

What it means

InitTablet with allowUpdate=true found an existing tablet record whose keyspace or shard differs from the one being registered. Vitess refuses to silently re-home a tablet into another shard because that would corrupt the serving topology. The fix requires explicitly deleting and re-adding the tablet, or passing the allowDifferentShard flag where available.

Source

Thrown at go/vt/topo/tablet.go:643

	if tablet.Type == topodatapb.TabletType_PRIMARY {
		// we update primary_term_start_time even if the primary hasn't changed
		// because that means a new primary term with the same primary
		tablet.PrimaryTermStartTime = protoutil.TimeToProto(time.Now())
	}

	err = ts.CreateTablet(ctx, tablet)
	if IsErrType(err, NodeExists) && allowUpdate {
		// Try to update then
		oldTablet, err := ts.GetTablet(ctx, tablet.Alias)
		if err != nil {
			return fmt.Errorf("failed reading existing tablet %v: %v", topoproto.TabletAliasString(tablet.Alias), err)
		}

		// Check we have the same keyspace / shard, and if not,
		// require the allowDifferentShard flag.
		if oldTablet.Keyspace != tablet.Keyspace || oldTablet.Shard != tablet.Shard {
			return fmt.Errorf("old tablet has shard %v/%v. Cannot override with shard %v/%v. Delete and re-add tablet if you want to change the tablet's keyspace/shard", oldTablet.Keyspace, oldTablet.Shard, tablet.Keyspace, tablet.Shard)
		}
		oldTablet.Tablet = tablet.CloneVT()
		if err := ts.UpdateTablet(ctx, oldTablet); err != nil {
			return fmt.Errorf("failed updating tablet %v: %v", topoproto.TabletAliasString(tablet.Alias), err)
		}
		return nil
	}
	return err
}

// ParseServingTabletType parses the tablet type into the enum, and makes sure
// that the enum is of serving type (PRIMARY, REPLICA, RDONLY/BATCH).
//
// Note: This function more closely belongs in topoproto, but that would create
// a circular import between packages topo and topoproto.
func ParseServingTabletType(param string) (topodatapb.TabletType, error) {
	servedType, err := topoproto.ParseTabletType(param)
	if err != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Delete the old tablet record: vtctldclient DeleteTablet <alias> (after ensuring it's not serving), then re-run InitTablet
2. Correct the -keyspace/-shard flags on vttablet to match the existing registration
3. If re-homing is intentional, use the flow that sets allowDifferentShard explicitly rather than plain InitTablet

Example fix

// before
vttablet -tablet_alias zone1-100 -keyspace commerce -shard 0
// after (record exists in commerce/1)
vtctldclient DeleteTablet zone1-100
vttablet -tablet_alias zone1-100 -keyspace commerce -shard 1

old, err := ts.GetTablet(ctx, alias)
if err == nil && (old.Keyspace != keyspace || old.Shard != shard) {
    return fmt.Errorf("alias %v registered in %v/%v; delete it first", alias, old.Keyspace, old.Shard)
}

if err := ts.InitTablet(ctx, tablet, false, true, false); err != nil {
    if strings.Contains(err.Error(), "Cannot override with shard") {
        // handle shard mismatch: delete + re-add, or fix flags
    }
    return err
}

When it happens

Trigger: Calling InitTablet for an alias already registered under a different keyspace/shard while allowUpdate is true and the allowDifferentShard precondition (same keyspace/shard) fails. Common via vttablet startup with a changed -keyspace/-shard flag, or test helpers addTablet/NewFakeTablet reusing UIDs.

Common situations: Operator edits vttablet's -shard or -keyspace flag but the old tablet record still exists in topo; reusing tablet UIDs across environments; copied Vitess configs pointing a tablet at a new shard without cleanup.

Related errors

• SrvVSchema has no entry for keyspace %v
• shard %v/%v has no primary
• can't get primary tablet record %v: %v
• cannot get (or create) shard %v/%v: %v
• shard %v/%v has a different KeyRange: %v != %v

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