vitessio/vitess · error

unknown metric name

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.

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

• duplicate metric name
• invalid metric name
• no app indicated
• could not find vindex column
• detailed_limit exceeds maximum allowed value

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

Appendix: 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)