grafana/k6 · error

parsing element handle screenshot options: %w

Error message

parsing element handle screenshot options: %w

What it means

Thrown synchronously by ElementHandle.screenshot() when its options fail to parse. ElementHandleScreenshotOptions (path, type, quality, omitBackground, timeout) is parsed with lenient coercions in common/element_handle_options.go and always returns nil, so this wrap is defensive in current k6. Notably an invalid type value (e.g. 'gif') is silently ignored and PNG is used, so format mistakes do not raise this error either.

Source

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

				if err != nil {
					return nil, err //nolint:wrapcheck
				}
				return mapFrame(vu, f), nil
			})
		},
		"press": func(key string, opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewElementHandlePressOptions(eh.DefaultTimeout())
			if err := popts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing press %q options: %w", key, err)
			}
			return promise(vu, func() (any, error) {
				return nil, eh.Press(key, popts) //nolint:wrapcheck
			}), nil
		},
		"screenshot": func(opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewElementHandleScreenshotOptions(eh.Timeout())
			if err := popts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing element handle screenshot options: %w", err)
			}

			return promise(vu, func() (any, error) {
				bb, err := eh.Screenshot(popts, vu.filePersister)
				if err != nil {
					return nil, err //nolint:wrapcheck
				}

				ab := rt.NewArrayBuffer(bb)

				return &ab, nil
			}), nil
		},
		"scrollIntoViewIfNeeded": func(opts sobek.Value) (*sobek.Promise, error) {
			popts := common.NewElementHandleBaseOptions(eh.DefaultTimeout())
			if err := popts.Parse(vu.Context(), opts); err != nil {
				return nil, fmt.Errorf("parsing scrollIntoViewIfNeeded options: %w", err)
			}

View on GitHub (pinned to 93accf6570)

Solutions

1. Use only { path, type: 'jpeg'|'png', quality, omitBackground, timeout } with matching types
2. If this message appears, upgrade k6 and retry with an empty options object to isolate it
3. Check the wrapped cause after the colon for the failing field in your build
4. For JPEG quality control set type: 'jpeg' explicitly or end path with .jpg/.jpeg

Example fix

// before
await el.screenshot({ path: 'shot.png', type: 'gif', quality: 'high' });

// after
await el.screenshot({ path: 'shot.png', type: 'png', quality: 90, timeout: 10000 });

if (opts?.type !== undefined && !['png', 'jpeg'].includes(opts.type)) {
  throw new Error(`screenshot(): invalid type '${opts.type}' (k6 silently falls back to PNG)`);
}
if (opts?.quality !== undefined && !Number.isInteger(opts.quality)) {
  throw new Error('screenshot(): quality must be an integer');
}

function isScreenshotOpts(o) {
  if (o == null) return true;
  return (o.path === undefined || typeof o.path === 'string') &&
         (o.type === undefined || ['png', 'jpeg'].includes(o.type)) &&
         (o.quality === undefined || Number.isInteger(o.quality)) &&
         (o.omitBackground === undefined || typeof o.omitBackground === 'boolean') &&
         (o.timeout === undefined || Number.isFinite(o.timeout));
}

try {
  const buf = await el.screenshot(opts);
} catch (e) {
  if (/parsing element handle screenshot options/.test(String(e.message))) {
    console.log(`fix screenshot options: ${e.message}`);
  } else throw e; // real failures (timeout, detached element) occur inside the promise
}

When it happens

Trigger: In current code none: path/type/quality/omitBackground/timeout all coerce leniently; an unknown type string is skipped and .jpg/.jpeg suffixes on path infer JPEG. Older structural Parse builds could fail the whole-object export.

Common situations: Assuming screenshot() validates type or quality (it does not: quality only matters for JPEG, invalid type falls back to PNG); scripts written against old xk6-browser; passing screenshot data as options instead of using the returned buffer.

Related errors

• parsing check options: %w
• parsing element click options: %w
• parsing element double click options: %w
• parsing element fill options: %w
• parsing element hover options: %w

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