vitessio/vitess · error

invalid shard path: %v

Error message

invalid shard path: %v

What it means

ParseKeyspaceShard expects a 'keyspace/shard' identifier separated by '/' (or the legacy ':'). The input string split into the wrong number of parts — either no separator or more than one — so no keyspace/shard pair could be extracted.

Source

Thrown at go/vt/topo/topoproto/shard.go:37

import (
	"fmt"
	"strings"
)

// KeyspaceShardString returns a "keyspace/shard" string taking
// keyspace and shard as separate inputs.
func KeyspaceShardString(keyspace, shard string) string {
	return keyspace + "/" + shard
}

// ParseKeyspaceShard parse a "keyspace/shard" or "keyspace:shard"
// string and extract both keyspace and shard
func ParseKeyspaceShard(param string) (string, string, error) {
	keySpaceShard := strings.Split(param, "/")
	if len(keySpaceShard) != 2 {
		keySpaceShard = strings.Split(param, ":")
		if len(keySpaceShard) != 2 {
			return "", "", fmt.Errorf("invalid shard path: %v", param)
		}
	}
	return keySpaceShard[0], keySpaceShard[1], nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Format the argument as keyspace/shard, e.g. commerce/0 or legacy commerce:0
2. Check shell quoting/escaping if the separator was lost
3. Verify you are not passing a tablet alias or keyspace-only string where keyspace/shard is required

Example fix

// before
vtctldclient EmergencyReparentShard commerce
// after
vtctldclient EmergencyReparentShard commerce/0

parts := strings.Split(arg, "/")
if len(parts) != 2 {
    return fmt.Errorf("expected keyspace/shard, got %q", arg)
}

func isKeyspaceShardFormat(s string) bool {
    parts := strings.Split(s, "/")
    return len(parts) == 2 && parts[0] != "" && parts[1] != ""
}

ks, shard, err := topoproto.ParseKeyspaceShard(arg)
if err != nil {
    return fmt.Errorf("--%s must be keyspace/shard (e.g. commerce/0): %w", flagName, err)
}

When it happens

Trigger: Passing a bare shard name, an empty string, a keyspace without shard ('commerce'), or a malformed identifier ('commerce/0/extra') to ParseKeyspaceShard via commands like BackupShard, GetBackups, EmergencyReparentShard, RemoveBackup, or ParseKeyspaceShards.

Common situations: Shell quoting stripping the '/' or passing just the shard; using '-' as separator; passing tablet alias 'zone1-100' instead of keyspace/shard; extra slashes in scripted commands.

Related errors

• 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
• old tablet has shard %v/%v. Cannot override with shard %v/%v

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