vitessio/vitess · critical · ErrNoShardPrimary

no primary found for shard

Error message

no primary found for shard

What it means

ErrNoShardPrimary is raised during vexec initialization when a shard in the target keyspace has no serving primary tablet. VExec must send its statements to each shard's primary, so a primary-less shard makes the operation impossible. It is a sentinel used by initialize().

Source

Thrown at go/vt/vtctl/workflow/vexec/vexec.go:54

)

const (
	// VExecTableQualifier is the qualifier that all tables supported by vexec
	// are prefixed by.
	VExecTableQualifier = "_vt"

	// VReplicationLogTableName is the unqualified name of the vreplication_log
	// table supported by vexec.
	VReplicationLogTableName = "vreplication_log"
	// VReplicationTableName is the unqualified name of the vreplication table
	// supported by vexec.
	VReplicationTableName = "vreplication"
)

var ( // Topo lookup errors.
	// ErrNoShardPrimary occurs when a shard is found with no serving
	// primary.
	ErrNoShardPrimary = errors.New("no primary found for shard")
	// ErrNoShardsForKeyspace occurs when attempting to run a vexec on an empty
	// keyspace.
	ErrNoShardsForKeyspace = errors.New("no shards found in keyspace")
)

var ( // Query parsing and planning errors.
	// ErrUnsupportedQuery occurs when attempting to run an unsupported query
	// through vexec.
	ErrUnsupportedQuery = errors.New("query not supported by vexec")
	// ErrUnsupportedTable occurs when attempting to run vexec on an unsupported
	// table. At the time of writing, this occurs when attempting to query any
	// table other than _vt.vreplication.
	ErrUnsupportedTable = errors.New("table not supported by vexec")
)

// VExec provides the main interface to planning and executing vexec queries
// (normally, queries on tables in the `_vt` database). It currently supports
// some limited vreplication queries; this set of supported behavior will expand

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Restore a primary for the shard (Elect/planned rebalance or InitializeShardPrimary) and verify it is SERVING in topology
2. Run RefreshState on the shard's tablets so the serving graph no longer lists a primary-less shard
3. Retry the vexec/workflow command once all shards report a primary

Example fix

# before: shard -80 has no primary
vtctldclient Workflow --keyspace customer --workflow sales Stop
# ErrNoShardPrimary: no primary found for shard
# after
vtctldclient PluralType -80 <new-replica> ; vtctldclient InitializeShardPrimary customer -80 <alias>
vtctldclient Workflow --keyspace customer --workflow sales Stop

for _, shard := range shardNames {
    si, err := ts.TopoServer().GetShard(ctx, keyspace, shard)
    if err != nil || si.PrimaryAlias == nil {
        return fmt.Errorf("shard %s/%s has no primary; cannot run vexec", keyspace, shard)
    }
}

func shardHasPrimary(si *topodatapb.ShardInfo) bool {
    return si != nil && si.PrimaryAlias != nil
}

if err := vexec.Execute(ctx); err != nil {
    if errors.Is(err, workflow.ErrNoShardPrimary) {
        return fmt.Errorf("elect a primary for all shards and retry: %w", err)
    }
    return err
}

When it happens

Trigger: Running VExec (e.g. MoveTables vexec-based cleanup or workflow commands touching _vt tables) while some shard in the keyspace has no PRIMARY tablet in serving state — primary down, primary demoted without a new election, or topo serving graph stale.

Common situations: After an emergency failover where the primary never got rebuilt, during manual repair of replication, or in degraded shards where vtctldclient PluralType replays never completed.

Related errors

• could not get RoutingRules
• cannot update immutable column
• unsupported query construct
• attempted to execute unprepared query
• no shards found in keyspace

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