grafana/k6 · error

missing required argument 'label'

Error message

missing required argument 'label'

What it means

Locator.getByLabel(label) in the k6 browser module requires a non-nullish first argument; the mapping layer in locator_mapping.go rejects it before browser communication. The label text (string or RegExp) is the only criterion for resolving labelled form controls beneath the locator's scope. Playwright's API has the same mandatory argument.

Source

Thrown at internal/js/modules/k6/browser/browser/locator_mapping.go:245

				}
				if !ok {
					return nil, nil
				}
				return s, nil
			}), nil
		},
		"getByAltText": func(alt sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(alt) {
				return nil, errors.New("missing required argument 'altText'")
			}
			palt, popts := parseGetByBaseOptions(vu.Context(), alt, false, opts)

			ml := mapLocator(vu, lo.GetByAltText(palt, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByLabel": func(label sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(label) {
				return nil, errors.New("missing required argument 'label'")
			}
			plabel, popts := parseGetByBaseOptions(vu.Context(), label, true, opts)

			ml := mapLocator(vu, lo.GetByLabel(plabel, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByPlaceholder": func(placeholder sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(placeholder) {
				return nil, errors.New("missing required argument 'placeholder'")
			}
			pplaceholder, popts := parseGetByBaseOptions(vu.Context(), placeholder, false, opts)

			ml := mapLocator(vu, lo.GetByPlaceholder(pplaceholder, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByRole": func(role sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(role) {
				return nil, errors.New("missing required argument 'role'")

View on GitHub (pinned to 93accf6570)

Solutions

1. Pass the label string or RegExp: formLocator.getByLabel('Username')
2. Default or validate the field's label before the call (label ?? field.name)
3. Fix the missing property/key producing undefined
4. Use a RegExp for labels with markers, e.g. getByLabel(/^Username/)

Example fix

// before
const user = page.locator('form').getByLabel(fields.user); // fields.user is undefined

// after
const user = page.locator('form').getByLabel('Username');

const label = field.label;
if (!isTextSelector(label)) throw new Error(`field.label required for getByLabel on ${field.id}`);
locator.getByLabel(label);

function isTextSelector(v) {
  return (typeof v === 'string' && v.length > 0) || v instanceof RegExp;
}

try {
  sub = locator.getByLabel(maybeLabel);
} catch (e) {
  if (/missing required argument 'label'/.test(String(e.message))) {
    throw new Error(`label missing for field ${field.id}`);
  }
  throw e;
}

When it happens

Trigger: Calling page.locator('form').getByLabel() with no argument, passing null/undefined, or forwarding an undefined label from a field-definition object in a page object.

Common situations: Form page objects driven by field maps with optional labels, i18n label sources that miss a key, variable renames during refactors.

Related errors

• missing required argument 'placeholder'
• missing required argument 'label'
• missing required argument 'placeholder'
• missing required argument 'label'
• missing required argument 'placeholder'

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