vitessio/vitess · error · ErrNoShardsForKeyspace

no shards found in keyspace

Error message

no shards found in keyspace

What it means

ErrNoShardsForKeyspace is thrown by the vexec package when a vexec command is run against a keyspace that contains zero shards. vexec plans and executes queries (currently only against _vt.vreplication) across all shards of a keyspace, so with no shards there is nothing to fan out to and planning cannot proceed. It is a sentinel error (errors.New) so callers can compare with errors.Is.

Source

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

	// 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
// over time. It may be extended to support schema_migrations queries as well.
type VExec struct {
	ts  *topo.Server

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the keyspace name is spelled correctly and exists (vtctldclient GetKeyspaces).
2. List shards with vtctldclient GetShards <keyspace> to confirm the keyspace actually has shards.
3. If the keyspace is intentionally empty, do not run vexec against it; create the needed shards/tablets first.
4. Check the topology service is healthy and you are pointed at the right global topo cells.

Example fix

// before
vexec.Run(ctx, ts, "UPDATE _vt.vreplication SET state='Running'", "wrong_keyspace")
// after
shards, _ := ts.GetShardNames(ctx, "commerce")
if len(shards) == 0 { return fmt.Errorf("keyspace commerce has no shards") }
vexec.Run(ctx, ts, "UPDATE _vt.vreplication SET state='Running'", "commerce")

shards, err := ts.GetShardNames(ctx, keyspace)
if err != nil { return err }
if len(shards) == 0 {
    return fmt.Errorf("keyspace %s has no shards; cannot run vexec", keyspace)
}

if err := vexec.Run(...); err != nil {
    if errors.Is(err, vexec.ErrNoShardsForKeyspace) {
        // keyspace empty: skip or fail with clear message
    }
    return err
}

When it happens

Trigger: Calling vexec (e.g. PlanQuery or the vtctld VExec handlers) against a keyspace whose shard list, fetched from the topology via ts.GetShardNames, is empty.

Common situations: Typo in the keyspace name passed to a vexec command; keyspace exists but all shards have been removed; topology (etcd/zk) is partially wiped; running vexec before a keyspace has been created or shards added.

Related errors

• cannot remove cell %v from shard %v/%v: %w
• parse error
• BaseKeyspace is required for SNAPSHOT keyspaces
• SnapshotTime is required for SNAPSHOT keyspaces
• no primary found for shard

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