vitessio/vitess · error

creating this tablet would override old primary %v in shard

Error message

creating this tablet would override old primary %v in shard %v/%v, use allow_master_override flag

What it means

When registering a PRIMARY tablet, InitTablet refuses to silently replace an existing primary in the shard record. This error is thrown when the shard already has a primary whose alias differs from the tablet being registered and allowPrimaryOverride is false. It protects against two primaries being recorded in one shard.

Source

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

		// create the parent keyspace and shard if needed
		si, err = ts.GetOrCreateShard(ctx, tablet.Keyspace, tablet.Shard)
	} else {
		si, err = ts.GetShard(ctx, tablet.Keyspace, tablet.Shard)
		if IsErrType(err, NoNode) {
			return errors.New("missing parent shard, use -parent option to create it, or CreateKeyspace / CreateShard")
		}
	}

	// get the shard, checks a couple things
	if err != nil {
		return fmt.Errorf("cannot get (or create) shard %v/%v: %v", tablet.Keyspace, tablet.Shard, err)
	}
	if !key.KeyRangeEqual(si.KeyRange, tablet.KeyRange) {
		return fmt.Errorf("shard %v/%v has a different KeyRange: %v != %v", tablet.Keyspace, tablet.Shard, si.KeyRange, tablet.KeyRange)
	}
	if tablet.Type == topodatapb.TabletType_PRIMARY && si.HasPrimary() && !topoproto.TabletAliasEqual(si.PrimaryAlias, tablet.Alias) && !allowPrimaryOverride {
		// InitTablet is deprecated, so the flag has not been renamed
		return fmt.Errorf("creating this tablet would override old primary %v in shard %v/%v, use allow_master_override flag", topoproto.TabletAliasString(si.PrimaryAlias), tablet.Keyspace, tablet.Shard)
	}

	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.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. If a failover already happened, do not re-register the old primary as PRIMARY: restart it as REPLICA (`vttablet ... -init_tablet_type REPLICA`) or run `vtctldclient RebuildKeyspaceGraph` after fixing its type.
2. Use the proper reparent workflow (`PlannerReparentShard` / `EmergencyReparentShard`) to change primaries instead of InitTablet.
3. If overriding is genuinely intended (e.g. disaster recovery of the topo record), pass allow_master_override/allowPrimaryOverride=true, after confirming the old primary alias is truly defunct.
4. Verify current shard state with `vtctldclient GetShard <keyspace>/<shard>` before any manual primary registration.

Example fix

// before (former primary restarting as PRIMARY, new primary exists)
vttablet -init_tablet_type PRIMARY ...   // would override old primary
// after: come back as replica, or failover properly
vttablet -init_tablet_type REPLICA ...
# or, for a true takeover:
vtctldclient EmergencyReparentShard commerce/-

// Check shard primary state before registering a PRIMARY tablet
si, _ := ts.GetShard(ctx, keyspace, shard)
if tablet.Type == topodatapb.TabletType_PRIMARY && si.HasPrimary() &&
    !topoproto.TabletAliasEqual(si.PrimaryAlias, tablet.Alias) {
    return fmt.Errorf("shard already has primary %s; use reparent workflow",
        topoproto.TabletAliasString(si.PrimaryAlias))
}

func shardPrimaryConflict(si *topo.ShardInfo, t *topodatapb.Tablet) bool {
    return t.Type == topodatapb.TabletType_PRIMARY && si.HasPrimary() &&
        !topoproto.TabletAliasEqual(si.PrimaryAlias, t.Alias)
}

if err := topotools.InitTablet(ctx, ts, false, tablet, cp); err != nil {
    if strings.Contains(err.Error(), "would override old primary") {
        // a promotion already happened; restart this tablet as REPLICA
        return fmt.Errorf("restart tablet with -init_tablet_type REPLICA or run EmergencyReparentShard: %w", err)
    }
    return err
}

When it happens

Trigger: Calling InitTablet with tablet.Type == PRIMARY while the shard record's PrimaryAlias points at a different tablet and allowPrimaryOverride (legacy allow_master_override) is not set — typically during manual tablet startup or an unplanned promotion via InitTablet instead of PlannerReparentShard/ElectNewPrimary.

Common situations: Restarting a former primary after a failover promoted another tablet (the topo still lists the new primary); running vttablet -init with primary type on a shard that already has a primary; DR/failover drills done by hand instead of via vtctld reparent commands; stale topo state after a network partition during a previous promotion.

Related errors

• cannot get (or create) shard %v/%v: %v
• shard %v/%v has a different KeyRange: %v != %v
• TabletExternallyReparented failed on primary %v: %v
• GetTabletMap(%v) failed: %w
• failed to get schema from tablet %v. err: %v

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