What causes "error parsing shard name %v: %v" in vitessio/vitess?

Read the wrapped %v error for the exact validation failure from topo.ValidateShardName.

error parsing shard name %v: %v

Error message

error parsing shard name %v: %v

What it means

After splitting a filter into keyspace and shard, NewFilterByShard validates the shard portion with topo.ValidateShardName (which also extracts keyranges like '-80'). If the shard name is not syntactically valid, this error wraps the validation failure.

Source

Thrown at go/vt/discovery/topology_watcher.go:370

// TopologyWatcher. Each filter is a keyspace|shard entry, where shard
// can either be a shard name, or a keyrange. All tablets that match
// at least one keyspace|shard tuple will be forwarded by the
// TopologyWatcher to its consumer.
func NewFilterByShard(filters []string, opts ...Option) (*FilterByShard, error) {
	m := make(map[string][]*filterShard)
	for _, filter := range filters {
		parts := strings.Split(filter, "|")
		if len(parts) != 2 {
			return nil, fmt.Errorf("invalid FilterByShard parameter: %v", filter)
		}

		keyspace := parts[0]
		shard := parts[1]

		// extract keyrange if it's a range
		canonical, kr, err := topo.ValidateShardName(shard)
		if err != nil {
			return nil, fmt.Errorf("error parsing shard name %v: %v", shard, err)
		}

		// check for duplicates
		for _, c := range m[keyspace] {
			if c.shard == canonical {
				return nil, fmt.Errorf("duplicate %v/%v entry", keyspace, shard)
			}
		}

		m[keyspace] = append(m[keyspace], &filterShard{
			keyspace: keyspace,
			shard:    canonical,
			keyRange: kr,
		})
	}

	fbs := &FilterByShard{
		filters: m,

View on GitHub (pinned to 01a25a7d17)

Solutions

Read the wrapped %v error for the exact validation failure from topo.ValidateShardName.
Fix the keyrange syntax: boundaries must be 2-character hex strings in ascending order, e.g. '-80', '80-', '40-80'.
Use '-' (empty range = whole keyspace) if you meant to watch all shards.
Validate shard names with topo.ValidateShardName in a quick unit check before configuring.

Example fix

// before
NewFilterByShard([]string{"commerce|80-40"}) // reversed range
// after
NewFilterByShard([]string{"commerce|40-80"})

Defensive patterns

Strategy: validation

Validate before calling

canonical, _, err := topo.ValidateShardName(shard)
if err != nil {
	return fmt.Errorf("shard %q invalid: %v", shard, err)
}
_ = canonical

Try / catch

fbs, err := discovery.NewFilterByShard(filters)
if err != nil {
	log.Exitf("bad shard name in tablet-filters: %v", err)
}

Prevention

Use 2-char hex boundaries in ascending order for keyranges ('40-80', not '80-40' or '-gg')
Run topo.ValidateShardName over shard names before writing configs
Copy shard names from the topology instead of typing them

When it happens

Trigger: Calling NewFilterByShard with a shard part that fails topo.ValidateShardName — e.g. mismatched keyrange boundaries ('80-40'), non-hex characters in a keyrange ('-gg'), or otherwise malformed range syntax.

Common situations: Hand-written shard ranges with reversed or non-hex boundaries; copy-paste of shard names with typos; confusion between numeric and keyrange-based shard naming in custom deployments.

Related errors

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