grafana/k6 · error

wrong polling option value: %q; possible values: "raf", "mut

Error message

wrong polling option value: %q; possible values: "raf", "mutation" or number

What it means

FrameWaitForFunctionOptions.Parse (frame_options.go:671) inspects the JS type of the `polling` option of frame.waitForFunction(). Only an int64-like number (fixed millisecond interval) or one of the strings "raf"/"mutation" is accepted; every other type or string falls through to this error. The number must actually be a number in the JS value (e.g. a string "100" is rejected).

Source

Thrown at internal/js/modules/k6/browser/common/frame_options.go:671

	obj := opts.ToObject(rt)
	for _, k := range obj.Keys() {
		v := obj.Get(k)
		switch k {
		case "timeout":
			o.Timeout = time.Duration(v.ToInteger()) * time.Millisecond
		case "polling":
			switch v.ExportType().Kind() {
			case reflect.Int64:
				o.Polling = PollingInterval
				o.Interval = v.ToInteger()
			case reflect.String:
				if p, ok := pollingTypeToID[v.ToString().String()]; ok {
					o.Polling = p
					break
				}
				fallthrough
			default:
				return fmt.Errorf("wrong polling option value: %q; "+
					`possible values: "raf", "mutation" or number`, v)
			}
		}
	}

	return nil
}

func NewFrameWaitForLoadStateOptions(defaultTimeout time.Duration) *FrameWaitForLoadStateOptions {
	return &FrameWaitForLoadStateOptions{
		Timeout: defaultTimeout,
	}
}

// Parse parses the frame waitForLoadState options.
func (o *FrameWaitForLoadStateOptions) Parse(ctx context.Context, opts sobek.Value) error {
	rt := k6ext.Runtime(ctx)
	if !common.IsNullish(opts) {

View on GitHub (pinned to 93accf6570)

Solutions

1. Use { polling: 'raf' } or { polling: 'mutation' } or a plain number of milliseconds, e.g. { polling: 100 }
2. If the value comes from config, coerce it before calling: Number(x) when it is numeric
3. Verify the argument order: waitForFunction(pageFunction, arg, options)

Example fix

// before
frame.waitForFunction(() => !!window.ready, {}, { polling: 'requestAnimationFrame' });

// after
frame.waitForFunction(() => !!window.ready, {}, { polling: 'raf' });
// or a fixed interval:
frame.waitForFunction(() => !!window.ready, {}, { polling: 100 });

function validPolling(v) {
  if (v === undefined) return v; // default
  if (typeof v === 'number' && Number.isFinite(v)) return v;
  if (v === 'raf' || v === 'mutation') return v;
  throw new Error('polling must be "raf", "mutation" or a number (ms)');
}
frame.waitForFunction(fn, arg, { ...opts, polling: validPolling(opts.polling) });

function isPolling(v: unknown): v is 'raf' | 'mutation' | number {
  return v === 'raf' || v === 'mutation' || (typeof v === 'number' && Number.isFinite(v));
}

When it happens

Trigger: frame.waitForFunction(fn, arg, { polling: 'requestAnimationFrame' }) (wrong alias), { polling: true }, { polling: 'every-100ms' }, or a stringified number { polling: '100' }. Passing options in the wrong argument position (second arg instead of third) can also surface unexpected types here.

Common situations: Translating Puppeteer's polling names (Puppeteer accepts only 'raf' or a number) or assuming any string constant works; also passing a config value that arrived as a string from JSON/env vars.

Related errors

• unmarshaling polling type: %w
• parsing goto options: %w
• parsing setContent options: %w
• parsing waitForNavigation options: %w
• %q is not a valid DOM state

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