grafana/k6 · error

setting screenshot background transparency: %w

Error message

setting screenshot background transparency: %w

What it means

For page.screenshot({omitBackground: true, format: 'png'}) the screenshotter first applies Emulation.setDefaultBackgroundColorOverride with a fully transparent RGBA(0,0,0,0). This error means that CDP command failed, so the transparent-background preparation could not be set up.

Source

Thrown at internal/js/modules/k6/browser/common/screenshotter.go:172

	}
	return p.resetViewport()
}

func (s *screenshotter) screenshot(
	sess session, doc, viewport *Rect, format ImageFormat, omitBackground bool, quality int64, path string,
) ([]byte, error) {
	var (
		buf  []byte
		clip *cdppage.Viewport
	)
	capture := cdppage.CaptureScreenshot()

	shouldSetDefaultBackground := omitBackground && format == "png"
	if shouldSetDefaultBackground {
		action := emulation.SetDefaultBackgroundColorOverride().
			WithColor(&cdp.RGBA{R: 0, G: 0, B: 0, A: 0})
		if err := action.Do(cdp.WithExecutor(s.ctx, sess)); err != nil {
			return nil, fmt.Errorf("setting screenshot background transparency: %w", err)
		}
	}

	// Add common options
	capture.WithQuality(quality)
	switch format {
	case ImageFormatJPEG:
		capture.WithFormat(cdppage.CaptureScreenshotFormatJpeg)
	default:
		capture.WithFormat(cdppage.CaptureScreenshotFormatPng)
	}

	visualViewportScale, visualViewportPageX, visualViewportPageY, err := getViewPortDimensions(s.ctx, sess, s.logger)
	if err != nil {
		return nil, err
	}

	if doc == nil {

View on GitHub (pinned to 93accf6570)

Solutions

1. Drop omitBackground:true — plain PNG screenshots skip the override entirely.
2. Make sure format:'png' + omitBackground are only used on an open, idle page (no goto/close in flight).
3. Retry once; transient 'session closed' errors often clear.
4. Pin/refresh the browser binary k6 uses (matching chrome/headless-shell version) via K6_BROWSER_PATH or a clean k6 browser cache.

Example fix

// before
await page.screenshot({ path: 's.png', omitBackground: true }); // fails if session unstable

// after
await page.screenshot({ path: 's.png', omitBackground: false }); // or omit the flag

if (page.isClosed()) throw new Error('page closed before screenshot');

try {
  await page.screenshot({ path: 's.png', omitBackground: true });
} catch (e) {
  if (String(e).includes('setting screenshot background transparency')) {
    await page.screenshot({ path: 's.png' }); // retry without transparency
  } else { throw e; }
}

When it happens

Trigger: page.screenshot({omitBackground:true, format:'png'}) executed while the CDP session is unusable: page/target closing, browser crash, session flat-protocol mismatch, or the command racing a navigation/Playwright-internal screenshot from another tab sharing the session.

Common situations: omitBackground:true on a page already being closed; headless-shell version mismatch between k6 and the fetched chromium (older chrome builds ignore/reject the override); flaky CDP WebSocket during container CPU throttling.

Related errors

• resetting screenshot background color: %w
• getting viewport dimensions: %w
• capturing screenshot: %w
• getting layout metrics for screenshot: %w
• setting viewport size to %s: %w

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