grafana/k6 · error

name %q is invalid

Error message

name %q is invalid

What it means

MetricEvent.Tag validates that the tag name used to group browser metrics is a non-empty, non-whitespace string. The value in matches.TagName was empty or only whitespace after TrimSpace, so the metric cannot be renamed/grouped and the tag call errors.

Source

Thrown at internal/js/modules/k6/browser/common/page.go:444

	// The patterns to match against.
	Matches []Match `js:"matches"`
}

// Match contains the fields that will be used to match against metric tags
// that are about to be emitted.
type Match struct {
	// This is a regex that will be compared against the existing url tag.
	URLRegEx string `js:"url"`
	// This is the request method to match on.
	Method string `js:"method"`
}

// Tag will find the first match given the URLTagPatterns and the URL from
// the metric tag and update the name field.
func (e *MetricEvent) Tag(rm RegExMatcher, matches TagMatches) error {
	name := strings.TrimSpace(matches.TagName)
	if name == "" {
		return fmt.Errorf("name %q is invalid", matches.TagName)
	}

	for _, m := range matches.Matches {
		// Validate the request method type if it has been assigned in a Match.
		method := strings.TrimSpace(m.Method)
		if method != "" {
			method = strings.ToUpper(method)
			switch method {
			case http.MethodGet, http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch,
				http.MethodHead, http.MethodOptions, http.MethodConnect, http.MethodTrace:
			default:
				return fmt.Errorf("method %q is invalid", m.Method)
			}

			if method != e.method {
				continue
			}
		}

View on GitHub (pinned to 93accf6570)

Solutions

1. Always pass a non-empty tagName: metric.tag({ tagName: 'my-group', matches: [{ url: '.*(\\?|&)id=\\d+' }] })
2. If the name is computed, default it: const name = computedName || 'default-group'
3. Log the tag object before calling tag() when debugging dynamic builders

Example fix

// before
page.on('metric', (metric) => {
  metric.tag({ matches: [{ url: '.*' }] }); // tagName missing
});

// after
page.on('metric', (metric) => {
  metric.tag({ tagName: 'api-calls', matches: [{ url: '.*' }] });
});

function tagMatches(m) {
  const name = (m.tagName || '').trim();
  if (!name) { throw new TypeError('metric tag requires a non-empty tagName'); }
  return m;
}
tagMatches(matches); metric.tag(matches);

function hasValidTagName(m) {
  return m !== null && typeof m === 'object' && typeof m.tagName === 'string' && m.tagName.trim() !== '';
}

When it happens

Trigger: Calling metric.tag(...) inside a page.on('metric') handler with tagName missing, empty (''), or whitespace-only: e.g. metric.tag({ matches: [{ url: '.*' }] }) (no tagName), or metric.tag({ tagName: ' ', matches: [...] }).

Common situations: Building the tag object dynamically and the name variable is undefined/empty; refactors that renamed the field (k6 expects tagName); copy-paste from examples that omitted the field.

Related errors

• method %q is invalid
• unknown error code: %s
• predicate function is not callable
• "handler" argument cannot be nil
• clip area is either empty or outside the viewport

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/67c8b23dc91d26fa. Report an issue: GitHub.