vitessio/vitess · error

failed to resolve keyspace wildcard %v: %v

Error message

failed to resolve keyspace wildcard %v: %v

What it means

keyspaceParamsToKeyspaces expands command-line keyspace parameters that may contain wildcards (e.g. 'customer*') by calling topo.ResolveKeyspaceWildcard. This error wraps any failure from the topology server during that resolution, preserving both the offending parameter and the underlying cause (typically a topo server connectivity or keyspace-not-found problem).

Source

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

// It supports topology-based wildcards, and plain wildcards.
// For instance:
// us*                             // using plain matching
// *                               // using plain matching
func keyspaceParamsToKeyspaces(ctx context.Context, wr *wrangler.Wrangler, params []string) ([]string, error) {
	result := make([]string, 0, len(params))
	for _, param := range params {
		if len(param) == 0 {
			return nil, errors.New("empty keyspace param in list")
		}
		if param[0] == '/' {
			// this is a topology-specific path
			result = append(result, params...)
		} else {
			// this is not a path, so assume a keyspace name,
			// possibly with wildcards
			keyspaces, err := wr.TopoServer().ResolveKeyspaceWildcard(ctx, param)
			if err != nil {
				return nil, fmt.Errorf("failed to resolve keyspace wildcard %v: %v", param, err)
			}
			result = append(result, keyspaces...)
		}
	}
	return result, nil
}

// shardParamsToKeyspaceShards builds a list of keyspace/shard pairs.
// It supports topology-based wildcards, and plain wildcards.
// For instance:
// user/*                             // using plain matching
// */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 {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped cause: if it says no keyspace found, fix the keyspace name/wildcard pattern
2. Verify topo server connectivity (vtctl should list the keyspace via `vtctl GetKeyspaces`)
3. List existing keyspaces and correct the wildcard pattern to match at least one
4. Retry after confirming topo server health (etcd/zookeeper reachable)

Example fix

// before
vtctl RebuildKeyspaceGraph 'custmer*'
// after
vtctl GetKeyspaces          # confirm real name
echo customer*              # verify glob matches
echo RebuildKeyspaceGraph 'customer*'

# Resolve the wildcard yourself before passing it on
vtctl GetKeyspaces | grep -E '^customer'   # ensure the pattern matches
keyspaces=$(vtctl GetKeyspaces | grep '^customer' | tr '\n' ' ')
vtctl RebuildKeyspaceGraph $keyspaces

if err := runVtctl("RebuildKeyspaceGraph", pattern); err != nil {
    if strings.Contains(err.Error(), "failed to resolve keyspace wildcard") {
        // inspect wrapped cause, log the pattern, fall back to explicit keyspace list
    }
}

When it happens

Trigger: Running any vtctl command that accepts keyspace params (via commandRebuildKeyspaceGraph and similar) where a parameter is treated as a keyspace name with wildcards and ResolveKeyspaceWildcard fails — e.g. the wildcard matches no keyspaces, or the topo server is unreachable.

Common situations: Typo in keyspace name so the wildcard matches nothing; topo server (etcd/zk) down or misconfigured; running against the wrong topo environment; stale cell configuration.

Related errors

• failed to resolve keyspace/shard wildcard %v: %v
• keyspace(%s) doesn't exist, check if the keyspace is initial
• SrvVSchema has no entry for keyspace %v
• old tablet has shard %v/%v. Cannot override with shard %v/%v
• unknown keyspace type: %v

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