{"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":172,"sourceCode":"\t}\n\treturn p.resetViewport()\n}\n\nfunc (s *screenshotter) screenshot(\n\tsess session, doc, viewport *Rect, format ImageFormat, omitBackground bool, quality int64, path string,\n) ([]byte, error) {\n\tvar (\n\t\tbuf  []byte\n\t\tclip *cdppage.Viewport\n\t)\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\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":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/grafana/k6/blob/93accf6570dcd306ca5e99cc44c393ee3797761b/internal/js/modules/k6/browser/common/screenshotter.go#L154-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop omitBackground:true — plain PNG screenshots skip the override entirely.","Make sure format:'png' + omitBackground are only used on an open, idle page (no goto/close in flight).","Retry once; transient 'session closed' errors often clear.","Pin/refresh the browser binary k6 uses (matching chrome/headless-shell version) via K6_BROWSER_PATH or a clean k6 browser cache."],"exampleFix":"// before\nawait page.screenshot({ path: 's.png', omitBackground: true }); // fails if session unstable\n\n// after\nawait page.screenshot({ path: 's.png', omitBackground: false }); // or omit the flag","handlingStrategy":"try-catch","validationCode":"if (page.isClosed()) throw new Error('page closed before screenshot');","typeGuard":null,"tryCatchPattern":"try {\n  await page.screenshot({ path: 's.png', omitBackground: true });\n} catch (e) {\n  if (String(e).includes('setting screenshot background transparency')) {\n    await page.screenshot({ path: 's.png' }); // retry without transparency\n  } else { throw e; }\n}","preventionTips":["Only use omitBackground on an open, idle page.","Do not combine omitBackground with racing navigations.","Verify the chromium binary matches the k6 version."],"tags":["k6","browser","screenshot","cdp","omit-background","transparency"],"backgroundTag":null,"analyzedSha":"93accf6570dcd306ca5e99cc44c393ee3797761b","analyzedAt":"2026-08-15T21:23:27.118Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}