vitessio/vitess · error

cannot get (or create) shard %v/%v: %v

Error message

cannot get (or create) shard %v/%v: %v

What it means

InitTablet registers a tablet record and fetches/creates its parent shard first. This error is thrown when the get-or-create of shard <keyspace>/<shard> itself failed — the shard record could be neither read nor created in the topo. It aborts tablet registration because a tablet must belong to an existing shard record.

Source

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

	tablet.Shard = shard
	tablet.KeyRange = kr

	// 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

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Pre-create the hierarchy: `vtctldclient CreateKeyspace` then `vtctldclient CreateShard` before starting the tablet, or pass -parent so InitTablet creates the shard.
2. Fix the keyspace/shard name on the tablet's flags — a typo makes it point at a keyspace that does not exist.
3. Check the wrapped inner error: topo unreachable → fix topo flags/connectivity; permission denied → fix topo ACLs.
4. Retry tablet startup once the topo is healthy; InitTablet is safe to re-run for a non-primary tablet.

Example fix

// before (tablet started before topology exists)
vttablet -keyspace commerce -shard "-" ...   // cannot get (or create) shard
// after
vtctldclient CreateKeyspace commerce
vtctldclient CreateShard commerce "-"
vttablet -keyspace commerce -shard "-" -parent ...

// Before starting a tablet, confirm shard exists
si, err := ts.GetShard(ctx, keyspace, shard)
if err != nil {
    return fmt.Errorf("create keyspace/shard %s/%s first: %w", keyspace, shard, err)
}

if err := topotools.InitTablet(ctx, ts, allowPrimary, tablet, cp); err != nil {
    if strings.Contains(err.Error(), "cannot get (or create) shard") {
        // create the keyspace/shard, then retry
        _ = ts.CreateShard(ctx, keyspace, shard)
        err = topotools.InitTablet(ctx, ts, allowPrimary, tablet, cp)
    }
    return err
}

When it happens

Trigger: Calling InitTablet (or legacy addTablet / vttablet startup with -init_shard creation path) when GetShard fails for a reason other than 'not found', or CreateShard fails (keyspace missing without -parent, topo write error, concurrent creation).

Common situations: Starting a vttablet before the keyspace/shard was created and without -parent; topo connectivity outage during tablet boot; wrong -keyspace/-shard spelling pointing at a nonexistent keyspace; topo RBAC blocking shard creation.

Related errors

• shard %v/%v has a different KeyRange: %v != %v
• shard %v/%v has no primary
• can't get primary tablet record %v: %v
• creating this tablet would override old primary %v in shard
• old tablet has shard %v/%v. Cannot override with shard %v/%v

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