vitessio/vitess · error

failed to parse tablet-filters value %q: %v

Error message

failed to parse tablet-filters value %q: %v

What it means

NewVTGateHealthCheckFilters validates the tablet-filters list by passing it to NewFilterByShard. If any filter entry cannot be parsed into a keyspace|shard pair, the whole filter construction fails with this error containing the joined filter string and the parse error.

Source

Thrown at go/vt/discovery/healthcheck.go:324

	// subscribers
	subscribers map[chan *TabletHealth]string
	// loadTabletsTrigger is used to immediately load information about tablets of a specific shard.
	loadTabletsTrigger chan topo.KeyspaceShard
	// options contains optional settings used to modify HealthCheckImpl
	// behavior.
	options Options
}

// NewVTGateHealthCheckFilters returns healthcheck filters for vtgate.
func NewVTGateHealthCheckFilters() (filters TabletFilters, err error) {
	if len(tabletFilters) > 0 {
		if len(KeyspacesToWatch) > 0 {
			return nil, errKeyspacesToWatchAndTabletFilters
		}

		fbs, err := NewFilterByShard(tabletFilters)
		if err != nil {
			return nil, fmt.Errorf("failed to parse tablet-filters value %q: %v", strings.Join(tabletFilters, ","), err)
		}
		filters = append(filters, fbs)
	} else if len(KeyspacesToWatch) > 0 {
		filters = append(filters, NewFilterByKeyspace(KeyspacesToWatch))
	}
	if len(tabletFilterTags) > 0 {
		filters = append(filters, NewFilterByTabletTags(tabletFilterTags))
	}
	return filters, nil
}

// NewHealthCheck creates a new HealthCheck object.
// Parameters:
// retryDelay.
//
//	The duration to wait before retrying to connect (e.g. after a failed connection
//	attempt).
//

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix each tablet-filters entry to the 'keyspace|shard' format, e.g. 'commerce|0' or 'commerce|-80'.
2. Check the wrapped %v message for the specific bad entry (invalid parameter, shard parse error, or duplicate).
3. Remove keyspaces-to-watch if you intend to use tablet-filters (the two are mutually exclusive).
4. Validate the filter list locally with NewFilterByShard before deploying the config.

Example fix

// before
fbs, err := NewFilterByShard([]string{"commerce.0"}) // invalid separator
// after
fbs, err := NewFilterByShard([]string{"commerce|0"})

for _, f := range tabletFilters {
	parts := strings.Split(f, "|")
	if len(parts) != 2 {
		return fmt.Errorf("bad tablet-filter %q: want keyspace|shard", f)
	}
}
if len(KeyspacesToWatch) > 0 && len(tabletFilters) > 0 {
	return errors.New("keyspaces-to-watch and tablet-filters are mutually exclusive")
}

filters, err := discovery.NewVTGateHealthCheckFilters()
if err != nil {
	log.Exitf("invalid tablet-filters config: %v", err)
}

When it happens

Trigger: Calling NewVTGateHealthCheckFilters (indirectly via createHealthCheck) with --tablet-filters values that are not valid 'keyspace|shard' entries — e.g. missing the '|' separator, invalid shard name/keyrange syntax, or duplicate entries; also combining tablet-filters with keyspaces-to-watch, which is rejected separately.

Common situations: Misconfigured VTGate command line: typo like 'commerce.0' instead of 'commerce|0'; using a comma-separated list where individual entries are invalid; stale configs from older flag formats; setting both tablet-filters and keyspaces-to-watch.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• could not find tablet: %s
• invalid FilterByShard parameter: %v
• duplicate %v/%v entry
• error creating discovery impl (%s): %w
• %s: unsupported URL host %s

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