grafana/k6 · error

missing required argument 'label'

Error message

missing required argument 'label'

What it means

FrameLocator.getByLabel(label) in the k6 browser module requires a non-nullish first argument; the mapping layer in frame_locator_mapping.go throws before contacting the browser. The label text (string or RegExp) identifies form controls by their associated label element, and without it the locator has no search criterion. This mirrors Playwright, where the label argument is mandatory.

Source

Thrown at internal/js/modules/k6/browser/browser/frame_locator_mapping.go:26

	k6common "go.k6.io/k6/v2/js/common"
)

// mapFrameLocator API to the JS module.
func mapFrameLocator(vu moduleVU, fl *common.FrameLocator) mapping {
	rt := vu.Runtime()
	return mapping{
		"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, fl.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, fl.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, fl.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: frameLocator.getByLabel('Email address')
2. Default or validate the data-sourced value before the call (const label = field.label ?? field.fallback)
3. Correct the typo/missing property that produces undefined
4. For labels with dynamic parts, use a RegExp such as getByLabel(/Email/)

Example fix

// before
const email = page.frameLocator('#form-frame').getByLabel(fieldName); // fieldName is undefined

// after
const fieldName = 'Email';
const email = page.frameLocator('#form-frame').getByLabel(fieldName);

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

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

try {
  loc = frameLocator.getByLabel(maybeLabel);
} catch (e) {
  if (/missing required argument 'label'/.test(String(e.message))) {
    throw new Error(`label missing for ${field.id}; check the form definition`);
  }
  throw e;
}

When it happens

Trigger: Calling page.frameLocator('iframe').getByLabel() with no argument, passing null/undefined, or passing a form-field name variable that is undefined because the test-data object lacks that key.

Common situations: Scripts iterating over form definitions where some entries have no label, renaming label variables during refactors, or optional-chained data access (form?.label) that silently yields undefined.

Related errors

• missing required argument 'placeholder'
• missing required argument 'altText'
• missing required argument 'role'
• missing required argument 'testId'
• missing required argument 'text'

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