grafana/k6 · error

parsing frame navigation options to

Error message

parsing frame navigation options to %q: %w

What it means

Thrown when `frame.goto(url, opts)` receives an invalid options value. The parseable keys are `referer` (string), `timeout` (ms), and `waitUntil` — an enum that must be exactly one of 'load', 'domcontentloaded', or 'networkidle' (validated by LifecycleEvent.UnmarshalText, which lists the valid values in the error). The URL is included in the message to identify the failing navigation.

Solutions

1. Use exactly 'load', 'domcontentloaded', or 'networkidle' (all lowercase) for waitUntil
2. Read the wrapped cause — it enumerates every valid lifecycle event value
3. If you copied from Playwright docs, drop unsupported events like 'commit' or 'interactive'

Example fix

// before
await frame.goto('https://example.com/', { waitUntil: 'networkIdle' });

// after
await frame.goto('https://example.com/', { waitUntil: 'networkidle' });

const WAIT_UNTIL = new Set(['load', 'domcontentloaded', 'networkidle']);
function assertGotoOpts(opts = {}) {
  if (opts.waitUntil !== undefined && !WAIT_UNTIL.has(opts.waitUntil)) {
    throw new Error(`waitUntil must be one of: ${[...WAIT_UNTIL].join(', ')}`);
  }
}

function isValidLifecycleEvent(v) {
  return v === 'load' || v === 'domcontentloaded' || v === 'networkidle';
}

try {
  await frame.goto(url, opts);
} catch (e) {
  if (/parsing frame navigation options .*invalid lifecycle event/.test(String(e))) {
    throw new Error(`Bad waitUntil in goto(${url}); use load|domcontentloaded|networkidle`);
  }
  throw e;
}

When it happens

Trigger: Calling `frame.goto('https://x/', { waitUntil: 'networkIdle' })` (camelCase typo), `{ waitUntil: 'domContentLoaded' }`, or any other string not in the enum. The underlying error reads: "invalid lifecycle event: %q; must be one of: domcontentloaded, load, networkidle".

Common situations: Porting Playwright scripts that assume case-insensitive or additional lifecycle names ('commit', 'interactive' in newer Playwright); typos like 'NetworkIdle' or 'network idle'; copy-pasting waitUntil values accepted by Puppeteer's Page.gotoOptions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• " " attribute is only supported for roles: "`).join(", ")}
• parsing setContent options
• getting frame title
• parse isEditable options of selector
• parse isEnabled options of selector

AI-assisted analysis of grafana/k6@8d06114777 (2026-09-14). Data as JSON: /api/errors/d257d033b7880ef2. Report an issue: GitHub.

Appendix: source

Thrown at internal/js/modules/k6/browser/browser/frame_mapping.go:205

			}
			ptext, popts := parseGetByBaseOptions(vu.Context(), text, true, opts)

			ml := mapLocator(vu, f.GetByText(ptext, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"getByTitle": func(title sobek.Value, opts sobek.Value) (*sobek.Object, error) {
			if k6common.IsNullish(title) {
				return nil, errors.New("missing required argument 'title'")
			}
			ptitle, popts := parseGetByBaseOptions(vu.Context(), title, false, opts)

			ml := mapLocator(vu, f.GetByTitle(ptitle, popts))
			return rt.ToValue(ml).ToObject(rt), nil
		},
		"goto": func(url string, opts sobek.Value) (*sobek.Promise, error) {
			gopts, err := parseFrameGotoOptions(rt, opts, f.Referrer(), f.NavigationTimeout())
			if err != nil {
				return nil, fmt.Errorf("parsing frame navigation options to %q: %w", url, err)
			}
			return promise(vu, func() (any, error) {
				resp, err := f.Goto(url, gopts)
				if err != nil {
					return nil, err //nolint:wrapcheck
				}

				return mapResponse(vu, resp), nil
			}), nil
		},
		"hover": func(selector string, opts sobek.Value) (*sobek.Promise, error) {
			popts, err := parseFrameHoverOptions(rt, opts, f.Timeout())
			if err != nil {
				return nil, fmt.Errorf("parsing hover options: %w", err)
			}
			return promise(vu, func() (any, error) {
				return nil, f.Hover(selector, popts) //nolint:wrapcheck
			}), nil

View on GitHub (pinned to 8d06114777)