vitessio/vitess · error

unknown metric name: %s

Error message

unknown metric name: %s

What it means

UpdateThrottlerConfig validates the requested throttler metric name against the set of metrics known to the throttle base package (base.KnownMetricNames). If req.MetricName is non-empty and not in that set, the RPC is rejected before any topo update so an invalid metric never reaches the throttlers.

Source

Thrown at go/vt/vtctl/grpcvtctldserver/server.go:2104

	return &vtctldatapb.GetSrvKeyspacesResponse{
		SrvKeyspaces: srvKeyspaces,
	}, nil
}

// UpdateThrottlerConfig updates throttler config for all cells
func (s *VtctldServer) UpdateThrottlerConfig(ctx context.Context, req *vtctldatapb.UpdateThrottlerConfigRequest) (resp *vtctldatapb.UpdateThrottlerConfigResponse, err error) {
	span, ctx := trace.NewSpan(ctx, "VtctldServer.UpdateThrottlerConfig")
	defer span.Finish()

	defer panicHandler(&err)

	if req.Enable && req.Disable {
		return nil, errors.New("--enable and --disable are mutually exclusive")
	}

	if req.MetricName != "" && !base.KnownMetricNames.Contains(base.MetricName(req.MetricName)) {
		return nil, fmt.Errorf("unknown metric name: %s", req.MetricName)
	}

	if len(req.AppCheckedMetrics) > 0 {
		specifiedMetrics := map[base.MetricName]bool{}
		for _, metricName := range req.AppCheckedMetrics {
			_, knownMetric, err := base.DisaggregateMetricName(metricName)
			if err != nil {
				return nil, fmt.Errorf("invalid metric name: %s", metricName)
			}
			if _, ok := specifiedMetrics[knownMetric]; ok {
				return nil, fmt.Errorf("duplicate metric name: %s", knownMetric)
			}
			specifiedMetrics[knownMetric] = true
		}
	}

	update := func(throttlerConfig *topodatapb.ThrottlerConfig) *topodatapb.ThrottlerConfig {
		if throttlerConfig == nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the accepted metric names (base.KnownMetricNames in go/vt/vttablet/tabletserver/throttle/base) and correct the metric name spelling/case.
2. Omit req.MetricName entirely if you do not intend to change the throttler's metric (empty string skips this check).
3. Upgrade/downgrade awareness: if a metric name was valid in another Vitess version, use a name valid for this version.

Example fix

// before
vtctldclient UpdateThrottlerConfig --metric-name loadavg
// after
vtctldclient UpdateThrottlerConfig --metric-name loadaverage

metric := base.MetricName(req.MetricName)
if req.MetricName != "" && !base.KnownMetricNames.Contains(metric) {
    return fmt.Errorf("metric %q not in known set %v", req.MetricName, base.KnownMetricNames)
}

When it happens

Trigger: Calling the UpdateThrottlerConfig vtctld RPC (or `vtctldclient UpdateThrottlerConfig --metric-name <name>`) with a --metric-name value that is not one of the known throttler metric names (e.g. a typo like 'loadavg' instead of the accepted names).

Common situations: Hand-typed vtctldclient commands, config templates copied from older Vitess versions where metric names changed, or automation passing a user-supplied metric name without validation.

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.

Related errors

• invalid metric name: %s
• duplicate metric name: %s
• no app indicated
• throttler not open
• failed to update throttler: %v err: %v

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