vitessio/vitess · error

failed to resolve keyspace/shard wildcard %v: %v

Error message

failed to resolve keyspace/shard wildcard %v: %v

What it means

shardParamsToKeyspaceShards expands keyspace/shard parameters that may contain wildcards (e.g. 'ks/-*') via topo.ResolveShardWildcard. This error wraps any failure from that resolution, such as no shards matching the wildcard pattern or topo server errors.

Source

Thrown at go/vt/vtctl/vtctl.go:878

// */0                                // using plain matching
func shardParamsToKeyspaceShards(ctx context.Context, wr *wrangler.Wrangler, params []string) ([]topo.KeyspaceShard, error) {
	result := make([]topo.KeyspaceShard, 0, len(params))
	for _, param := range params {
		if param[0] == '/' {
			// this is a topology-specific path
			for _, path := range params {
				keyspace, shard, err := topoproto.ParseKeyspaceShard(path)
				if err != nil {
					return nil, err
				}
				result = append(result, topo.KeyspaceShard{Keyspace: keyspace, Shard: shard})
			}
		} else {
			// this is not a path, so assume a keyspace
			// name / shard name, each possibly with wildcards
			keyspaceShards, err := wr.TopoServer().ResolveShardWildcard(ctx, param)
			if err != nil {
				return nil, fmt.Errorf("failed to resolve keyspace/shard wildcard %v: %v", param, err)
			}
			result = append(result, keyspaceShards...)
		}
	}
	return result, nil
}

// tabletParamsToTabletAliases takes multiple params and converts them
// to tablet aliases.
func tabletParamsToTabletAliases(params []string) ([]*topodatapb.TabletAlias, error) {
	result := make([]*topodatapb.TabletAlias, len(params))
	var err error
	for i, param := range params {
		result[i], err = topoproto.ParseTabletAlias(param)
		if err != nil {
			return nil, err
		}
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped cause and fix the keyspace/shard pattern
2. List shards first with `vtctl ListShards <keyspace>` and build the pattern from real shard names
3. Confirm topo server reachability before retrying
4. Use exact shard names instead of wildcards to avoid ambiguous globs

Example fix

// before
vtctl DeleteShard 'commerce/-'
// after
vtctl ListShards commerce   # see actual shards, e.g. 0
echo vtctl DeleteShard 'commerce/0'

# Confirm shards exist before wildcarding
vtctl ListShards commerce   # inspect shard names
# then pass explicit keyspace/shard values
echo vtctl DeleteShard commerce/0

if err := runVtctl("DeleteShard", ksShard); err != nil {
    if strings.Contains(err.Error(), "failed to resolve keyspace/shard wildcard") {
        // log ksShard and the wrapped topo error; prompt for exact shard
    }
}

When it happens

Trigger: Running a shard-scoped command like commandDeleteShard with a keyspace/shard argument (not a full path) whose wildcard resolves to nothing or fails in the topo server.

Common situations: Typo in shard name; wildcard matches no shards because the shard was already deleted or never existed; topo connectivity problems; confusing keyrange-style shard names.

Related errors

• failed to resolve keyspace wildcard %v: %v
• shard %v/%v has no primary
• can't get primary tablet record %v: %v
• cannot get (or create) shard %v/%v: %v
• shard %v/%v has a different KeyRange: %v != %v

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