setting screenshot background transparency

Error message

setting screenshot background transparency: %w

What it means

Thrown when preparing a screenshot with omitBackground (transparent background) in PNG format: the module first calls CDP Emulation.SetDefaultBackgroundColorOverride with a fully transparent RGBA(0,0,0,0), and if that CDP action fails this error wraps it. It only runs when omitBackground && format == 'png' — JPEG never sets a transparent background (JPEG cannot be transparent).

Solutions

Confirm you are using type 'png' — omitBackground with jpeg is ignored, so a failure here means png was set.
Check the wrapped CDP error: target/session errors mean the page is gone — screenshot earlier or guard with page.isClosed().
Retry once; transient session issues during navigation can break a single override call.
Drop omitBackground if transparency is not required.

Example fix

// before
await page.screenshot({ path: 'shot.png', omitBackground: true }); // during teardown

// after
if (!page.isClosed()) {
  await page.screenshot({ path: 'shot.png', omitBackground: true });
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!page.isClosed() && type === 'png') { /* safe to use omitBackground */ }

Try / catch

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

Prevention

omitBackground only works with png — don't set it for jpeg.
Avoid transparent screenshots in the final moments before browser close.
Treat transparency as optional so a fallback capture is acceptable.

When it happens

Trigger: page.screenshot({ omitBackground: true, type: 'png' }) on a page whose CDP session is broken or closing; browser/target crash mid-screenshot; very rarely, a Chromium version rejecting the override.

Common situations: Capturing transparent screenshots near the end of a test while the browser is being torn down; Chrome crash under memory pressure; the same screenshot works without omitBackground because the extra CDP call is skipped.

Related errors

AI-assisted analysis of grafana/k6@3fcf5388d7 (2026-09-20). Data as JSON: /api/errors/9c5847ea1eb6cb90. Report an issue: GitHub.

Appendix: source

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

func (s *screenshotter) screenshot(
	sess session, doc, viewport *Rect, format ImageFormat, omitBackground bool, quality int64, path string,
) (buf []byte, err error) {
	var 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})
		defer func() {
			ctx, cancel := s.cleanupContext()
			defer cancel()
			if restoreErr := emulation.SetDefaultBackgroundColorOverride().Do(cdp.WithExecutor(ctx, sess)); restoreErr != nil {
				err = errors.Join(err, fmt.Errorf("resetting screenshot background color: %w", restoreErr))
			}
		}()
		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 3fcf5388d7)