vitessio/vitess · error

can't lock shard: shard name is unspecified

Error message

can't lock shard: shard name is unspecified

What it means

LockShard acquires a cluster-wide lock on a keyspace-shard so only one recovery/action touches it at a time. This error is thrown when the shard argument is an empty string, meaning the caller tried to lock a shard without naming it. It is a precondition failure, not a lock-contention error.

Source

Thrown at go/vt/vtorc/logic/topology_recovery.go:246

	urgentOperations = cache.New(urgentOperationsInterval, 2*urgentOperationsInterval)
	go initializeTopologyRecoveryPostConfiguration()
}

func initializeTopologyRecoveryPostConfiguration() {
	config.WaitForConfigurationToBeLoaded()
}

func getLockAction(tabletAlias *topodatapb.TabletAlias, code inst.AnalysisCode) string {
	return fmt.Sprintf("VTOrc Recovery for %v on %v", code, topoproto.TabletAliasString(tabletAlias))
}

// LockShard locks the keyspace-shard preventing others from performing conflicting actions.
func LockShard(ctx context.Context, keyspace, shard, lockAction string) (context.Context, func(*error), error) {
	if keyspace == "" {
		return nil, nil, errors.New("can't lock shard: keyspace is unspecified")
	}
	if shard == "" {
		return nil, nil, errors.New("can't lock shard: shard name is unspecified")
	}
	if hasReceivedSIGTERM.Load() > 0 {
		return nil, nil, errors.New("can't lock shard: SIGTERM received")
	}

	startTime := time.Now()
	defer func() {
		lockTime := time.Since(startTime)
		shardLockTimings.Add("Lock", lockTime)
	}()

	shardsLockCounter.Add(1)
	ctx, unlock, err := ts.TryLockShard(ctx, keyspace, shard, lockAction)
	if err != nil {
		shardsLockCounter.Add(-1)
		return nil, nil, err
	}
	return ctx, func(e *error) {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the analysisEntry that led to the recovery; ensure AnalyzedShard is populated before recovery execution
2. Verify the topology detection code that produced the entry sets shard information
3. For manual/programmatic calls, pass a valid shard name from the keyspace's shard set

Example fix

// before
ctx, unlock, err := LockShard(ctx, keyspace, "", lockAction)
// after
if shard == "" {
    return fmt.Errorf("cannot lock: shard not resolved for keyspace %s", keyspace)
}
ctx, unlock, err := LockShard(ctx, keyspace, shard, lockAction)

if keyspace == "" || shard == "" {
    return fmt.Errorf("LockShard requires non-empty keyspace and shard, got %q/%q", keyspace, shard)
}
ctx, unlock, err := logic.LockShard(ctx, keyspace, shard, lockAction)

When it happens

Trigger: executeCheckAndRecoverFunction (or any caller of logic.LockShard) passes an empty shard value, typically because the recovery analysisEntry had no AnalyzedShard set (e.g. keyspace-wide or non-shard-specific analysis).

Common situations: Running vtorc recovery for an analysis entry that was computed at cluster level rather than shard level; a nil/empty shard field propagated from a detection entry; custom recovery automation calling LockShard with an incomplete keyspace/shard pair.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• can't lock shard: keyspace is unspecified
• can't lock shard: SIGTERM received
• cluster type can be only one of vitess or mysql
• no function closure for Event stream specified
• both atomic copy and partial mode cannot be specified for th

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