vitessio/vitess · error

failed to resolve keyspace/shard wildcard

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.

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
• can't get primary tablet record
• cannot get (or create) shard
• failed reading tablet
• failed to lock / ; if you really want to delete this shard…

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

Appendix: 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)