{"record":{"id":"9c5847ea1eb6cb90","repo":"grafana/k6","slug":"setting-screenshot-background-transparency-w","errorCode":null,"errorMessage":"setting screenshot background transparency: %w","messagePattern":"setting screenshot background transparency: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/js/modules/k6/browser/common/screenshotter.go","lineNumber":194,"sourceCode":"func (s *screenshotter) screenshot(\n\tsess session, doc, viewport *Rect, format ImageFormat, omitBackground bool, quality int64, path string,\n) (buf []byte, err error) {\n\tvar clip *cdppage.Viewport\n\tcapture := cdppage.CaptureScreenshot()\n\n\tshouldSetDefaultBackground := omitBackground && format == \"png\"\n\tif shouldSetDefaultBackground {\n\t\taction := emulation.SetDefaultBackgroundColorOverride().\n\t\t\tWithColor(&cdp.RGBA{R: 0, G: 0, B: 0, A: 0})\n\t\tdefer func() {\n\t\t\tctx, cancel := s.cleanupContext()\n\t\t\tdefer cancel()\n\t\t\tif restoreErr := emulation.SetDefaultBackgroundColorOverride().Do(cdp.WithExecutor(ctx, sess)); restoreErr != nil {\n\t\t\t\terr = errors.Join(err, fmt.Errorf(\"resetting screenshot background color: %w\", restoreErr))\n\t\t\t}\n\t\t}()\n\t\tif err := action.Do(cdp.WithExecutor(s.ctx, sess)); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"setting screenshot background transparency: %w\", err)\n\t\t}\n\t}\n\n\t// Add common options\n\tcapture.WithQuality(quality)\n\tswitch format {\n\tcase ImageFormatJPEG:\n\t\tcapture.WithFormat(cdppage.CaptureScreenshotFormatJpeg)\n\tdefault:\n\t\tcapture.WithFormat(cdppage.CaptureScreenshotFormatPng)\n\t}\n\n\tvisualViewportScale, visualViewportPageX, visualViewportPageY, err := getViewPortDimensions(s.ctx, sess, s.logger)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif doc == nil {","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/grafana/k6/blob/3fcf5388d78cb382f0c0d42ec556a06bfd1b8dee/internal/js/modules/k6/browser/common/screenshotter.go#L176-L212","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait page.screenshot({ path: 'shot.png', omitBackground: true }); // during teardown\n\n// after\nif (!page.isClosed()) {\n  await page.screenshot({ path: 'shot.png', omitBackground: true });\n}","handlingStrategy":"try-catch","validationCode":"if (!page.isClosed() && type === 'png') { /* safe to use omitBackground */ }","typeGuard":null,"tryCatchPattern":"try {\n  await page.screenshot({ path: 't.png', omitBackground: true });\n} catch (e) {\n  if (/setting screenshot background transparency/i.test(String(e))) {\n    await page.screenshot({ path: 't.png' }); // retry without transparency\n  } else throw e;\n}","preventionTips":["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."],"tags":["k6","browser","screenshot","omit-background","cdp"],"backgroundTag":"cdp-command-failed","analyzedSha":"3fcf5388d78cb382f0c0d42ec556a06bfd1b8dee","analyzedAt":"2026-09-20T22:01:45.163Z","contentChangedAt":"2026-09-20T22:01:45.163Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}