grafana/k6 · error

Invalid metric name: '%s'. %s

Error message

Invalid metric name: '%s'. %s

What it means

Raised by Registry.NewMetric when the metric name fails the name regex: it must start with a letter or underscore, contain only ASCII letters/digits/underscores, and be at most 128 characters. The message appends a static explanation (badNameWarning).

Source

Thrown at metrics/registry.go:48

	nameRegexString = "^[a-zA-Z_][a-zA-Z0-9_]{1,128}$"
	badNameWarning  = "Metric names must only include up to 128 ASCII letters, numbers, or underscores " +
		"and start with a letter or an underscore."
)

var compileNameRegex = regexp.MustCompile(nameRegexString)

func checkName(name string) bool {
	return compileNameRegex.MatchString(name)
}

// NewMetric returns new metric registered to this registry
// TODO have multiple versions returning specific metric types when we have such things
func (r *Registry) NewMetric(name string, typ MetricType, t ...ValueType) (*Metric, error) {
	r.l.Lock()
	defer r.l.Unlock()

	if !checkName(name) {
		return nil, fmt.Errorf("Invalid metric name: '%s'. %s", name, badNameWarning) //nolint:staticcheck
	}
	oldMetric, ok := r.metrics[name]

	if !ok {
		m := r.newMetric(name, typ, t...)
		r.metrics[name] = m
		return m, nil
	}
	if oldMetric.Type != typ {
		return nil, fmt.Errorf("metric '%s' already exists but with type %s, instead of %s", name, oldMetric.Type, typ)
	}
	if len(t) > 0 {
		if t[0] != oldMetric.Contains {
			return nil, fmt.Errorf("metric '%s' already exists but with a value type %s, instead of %s",
				name, oldMetric.Contains, t[0])
		}
	}
	return oldMetric, nil

View on GitHub (pinned to 01ffac6f24)

Solutions

1. Rename the metric to match [a-zA-Z_][a-zA-Z0-9_]{1,128}
2. Remove spaces, dashes, dots or other special characters
3. Prefix with a letter or underscore, not a digit

When it happens

Trigger: Thrown at metrics/registry.go:48 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of grafana/k6@01ffac6f24 (2026-08-18). Data as JSON: /api/errors/472c97a33c71a873. Report an issue: GitHub.