vitessio/vitess · error

shard %v/%v has a different KeyRange: %v != %v

Error message

shard %v/%v has a different KeyRange: %v != %v

What it means

InitTablet verifies that the shard record's KeyRange matches the KeyRange the tablet claims. This error is thrown when si.KeyRange (stored on the shard) differs from tablet.KeyRange, meaning the tablet thinks it belongs to a range that the topo's shard record does not cover. A tablet with the wrong keyrange would receive incorrect keyrouting, so registration is refused.

Source

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

	// get the shard, possibly creating it
	var si *ShardInfo

	if createShardAndKeyspace {
		// 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)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Correct the tablet's -keyrange/-shard flags to match the shard record shown in the error (`vtctldclient GetShard <keyspace>/<shard>`).
2. If the shard record itself is wrong, fix it (delete/recreate shard with the right KeyRange) then RebuildKeyspaceGraph, and re-run InitTablet.
3. After a reshard, restart the tablet with the flags of its new shard rather than reusing the old startup script.
4. Regenerate tablet startup configs from a template keyed on shard name to keep -shard and -keyrange in sync.

Example fix

// before
vttablet -keyspace commerce -shard "80-" -keyrange "-80" ...  // mismatch
// after
vttablet -keyspace commerce -shard "80-" -keyrange "80-" ...

// Verify the tablet flags match the shard record before InitTablet
si, _ := ts.GetShard(ctx, keyspace, shard)
if !key.KeyRangeEqual(si.KeyRange, tablet.KeyRange) {
    return fmt.Errorf("fix -keyrange: shard has %v, tablet claims %v",
        si.KeyRange, tablet.KeyRange)
}

func keyRangesMatch(a, b *topodatapb.KeyRange) bool {
    return key.KeyRangeEqual(a, b)
}

if err := topotools.InitTablet(ctx, ts, false, tablet, cp); err != nil {
    if strings.Contains(err.Error(), "has a different KeyRange") {
        return fmt.Errorf("tablet startup flags disagree with shard record; re-sync from shard plan: %w", err)
    }
    return err
}

When it happens

Trigger: Calling InitTablet (or vttablet boot / addTablet in tests) with -keyrange that does not equal the KeyRange stored on the shard record for keyspace/shard — e.g. tablet says 80- but shard record was created with -80.

Common situations: Copy-pasted vttablet startup scripts where -shard and -keyrange drifted; resharding moved a tablet to a new shard but the old flags remained; manual shard creation with wrong boundaries; restoring a tablet from backup into a different shard.

Related errors

• cannot get (or create) shard %v/%v: %v
• shard %v/%v has no primary
• can't get primary tablet record %v: %v
• non-contiguous KeyRange values for %v in cell %v at shard %v
• creating this tablet would override old primary %v in shard

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