vitessio/vitess · error

failed to get shard %s/%s/: %w

Error message

failed to get shard %s/%s/: %w

What it means

During RefreshTablets (shard-level tablet refresh), the shard record itself could not be fetched from the topology. The keyspace/shard lookup error is wrapped and returned, aborting the refresh of all tablets in that shard.

Source

Thrown at go/vt/vtctl/grpcvtctldserver/server.go:3445

	defer panicHandler(&err)

	if req.Keyspace == "" {
		err = vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, "RefreshStateByShard requires a keyspace")
		return nil, err
	}

	if req.Shard == "" {
		err = vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, "RefreshStateByShard requires a shard")
		return nil, err
	}

	ctx, cancel := context.WithTimeout(ctx, topo.RemoteOperationTimeout)
	defer cancel()

	si, err := s.ts.GetShard(ctx, req.Keyspace, req.Shard)
	if err != nil {
		err = fmt.Errorf("failed to get shard %s/%s/: %w", req.Keyspace, req.Shard, err)
		return nil, err
	}

	isPartial, partialDetails, err := topotools.RefreshTabletsByShard(ctx, s.ts, s.tmc, si, req.Cells, logutil.NewCallbackLogger(func(e *logutilpb.Event) {
		switch e.Level {
		case logutilpb.Level_WARNING:
			log.Warn(e.Value)
		case logutilpb.Level_ERROR:
			log.Error(e.Value)
		default:
			log.Info(e.Value)
		}
	}))
	if err != nil {
		return nil, err
	}

	return &vtctldatapb.RefreshStateByShardResponse{

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the shard exists: `vtctldclient GetShard <keyspace> <shard>`
2. Correct keyspace/shard spelling in the command or script
3. Check topo server connectivity and permissions
4. If the shard was intentionally deleted, skip the refresh for it

Example fix

// before
vtctldclient RefreshTablets commerce/0 typo
// after
vtctldclient GetShard commerce 0
vtctldclient RefreshTablets commerce/0

// verify the shard exists before refreshing tablets
if _, err := vtctld.GetShard(ctx, keyspace, shard); err != nil {
    return fmt.Errorf("shard %s/%s does not exist: %w", keyspace, shard, err)
}

// distinguish topo-not-found from transient topo errors
if errors.Is(err, topo.ErrNodeNotFound) {
    return nil // shard gone; nothing to refresh
}
return retryRefreshTablets(ctx, req)

When it happens

Trigger: RefreshTablets RPC (e.g. from vtctldclient RefreshTablets or RemoveKeyspaceCell flows) where topo.GetShard fails because the shard doesn't exist, keyspace is mistyped, or the topo server is unreachable.

Common situations: Keyspace/shard already deleted by concurrent operation; typo in keyspace or shard name; etcd/zk outage or ACL denying read.

Related errors

• parse error
• no shards found in keyspace
• no local cells have been created yet
• failed to delete tablet: %w
• failed to GetCellsAliases for cluster %s: %w

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