grafana/k6 · error

parsing check options: %w

Error message

parsing check options: %w

What it means

Thrown synchronously by ElementHandle.check() when its options object fails to parse. check() reuses ElementHandleSetCheckedOptions (a base-pointer options set: force, noWaitAfter, timeout, trial, strict, position), and in common/element_handle_options.go the only Parse step that can return an error is exporting the 'position' key into a map[string]float64. Because mapElementHandle's mapping returns (nil, error) before the promise is created, this surfaces as a plain JS exception at call time, not as a promise rejection.

Source

Thrown at internal/js/modules/k6/browser/browser/element_handle_mapping.go:31

// mapElementHandle to the JS module.
func mapElementHandle(vu moduleVU, eh *common.ElementHandle) mapping { //nolint:gocognit,funlen,cyclop
	rt := vu.Runtime()
	maps := mapping{
		"boundingBox": func() *sobek.Promise {
			return promise(vu, func() (any, error) {
				box, err := eh.BoundingBox()
				// We want to avoid errors when an element is not visible or detached and instead
				// opt to return a nil rectangle -- this matches Playwright's behaviour.
				if errors.Is(err, common.ErrElementNotVisible) || errors.Is(err, common.ErrElementNotAttachedToDOM) {
					return nil, nil
				}
				return box, err
			})
		},
		"check": func(opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewElementHandleSetCheckedOptions(eh.DefaultTimeout())
			if err := popts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing check options: %w", err)
			}
			return promise(vu, func() (any, error) {
				return nil, eh.Check(popts) //nolint:wrapcheck
			}), nil
		},
		"click": func(opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewElementHandleClickOptions(eh.Timeout())
			if err := popts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing element click options: %w", err)
			}

			return promise(vu, func() (any, error) {
				err := eh.Click(popts)
				return nil, err //nolint:wrapcheck
			}), nil
		},
		"contentFrame": func() *sobek.Promise {
			return promise(vu, func() (any, error) {

View on GitHub (pinned to 93accf6570)

Solutions

1. Pass position as an object with numeric x/y: el.check({ position: { x: 10, y: 20 } })
2. Omit position entirely to check the element at its default clickable center
3. Coerce computed coordinates with Number() and verify with Number.isFinite before building the options object
4. Wrap the call in try/catch (not .catch) since the error is thrown synchronously, before a promise exists

Example fix

// before
await el.check({ position: 'center' });

// after
await el.check({}); // default center, or:
const box = await el.boundingBox();
await el.check({ position: { x: box.x + 5, y: box.y + 5 } });

const p = opts?.position;
if (p !== undefined && (typeof p !== 'object' || Array.isArray(p) ||
    !Number.isFinite(Number(p.x)) || !Number.isFinite(Number(p.y)))) {
  throw new Error('check(): position must be { x: number, y: number }');
}

function isValidPosition(p) {
  if (p === undefined || p === null) return true;
  return typeof p === 'object' && !Array.isArray(p) &&
    Number.isFinite(Number(p.x)) && Number.isFinite(Number(p.y));
}
function isCheckOpts(o) {
  return o == null || isValidPosition(o.position); // force/noWaitAfter/timeout/strict/trial coerce safely
}

try {
  await el.check(opts);
} catch (e) {
  if (/parsing check options/.test(String(e.message))) {
    console.log(`bad check options: ${e.message}`); // fix position shape and retry
  } else throw e;
}

When it happens

Trigger: Calling el.check({ position: 'center' }) (string instead of object), { position: [10, 10] } (array), { position: { x: '10', y: 20 } } (x is a string), or position set to a number/boolean. Any non-object position, or an object whose x/y cannot export to float64, makes rt.ExportTo fail and the error is wrapped as 'parsing check options'. Scalar options (timeout, force, strict, trial) are lenient coercions and never produce this error; unknown keys are silently ignored.

Common situations: Porting Playwright scripts where position is documented as {x, y} but the value is built from strings (e.g. values read from getAttribute or a config file), or where a CSS keyword like 'center' is passed instead of computed coordinates. Also hit when options objects are constructed dynamically and position is accidentally set to null-like sentinels or arrays.

Related errors

• parsing element click options: %w
• parsing element double click options: %w
• parsing element fill options: %w
• parsing element hover options: %w
• parsing element input value options: %w

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