Puppeteer Screenshot Has Transparent Background Instead of White

If a Puppeteer screenshot is transparent instead of white, check the options passed to page.screenshot(). Set omitBackground: false or remove that option. Puppeteer documents false as the default; setting it explicitly is useful when screenshot options are shared or conditionally assembled.

await page.screenshot({ path: 'screenshot.png', omitBackground: false });

To intentionally allow a transparent background, use omitBackground: true. Puppeteer documents PNG as the default screenshot type, and PNG can preserve transparency. See the Puppeteer ScreenshotOptions API for the option and format behavior.

1. Set the screenshot background explicitly

Use an explicit value at the screenshot call when the output must have the browser’s normal white background:

await page.screenshot({
  path: 'screenshot.png',
  type: 'png',
  omitBackground: false,
});

Explicitly setting false prevents an inherited option object or conditional code path from silently enabling transparency. If you do not need to override a shared option, omitting omitBackground also uses Puppeteer’s documented default.

For an intentionally transparent capture:

await page.screenshot({
  path: 'screenshot.png',
  type: 'png',
  omitBackground: true,
});

The option controls the browser’s default white background. It does not mean Puppeteer will erase a background deliberately painted by the page’s CSS. If the page itself paints a color, inspect its styles separately.

2. Minimal runnable example

This example opens a page, captures a PNG with the default white background enabled, and closes the browser even if capture fails:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
    await page.screenshot({
      path: 'screenshot.png',
      type: 'png',
      omitBackground: false,
      fullPage: true,
    });
  } finally {
    await browser.close();
  }
})();

Run it in a project with Puppeteer installed. If your project uses ECMAScript modules, replace the CommonJS import with import puppeteer from 'puppeteer'; and keep the remaining code inside an async function.

3. Diagnose the saved image

Inspect the actual screenshot options. Look at the object passed to page.screenshot(), including values added through object spreads, helper functions, or environment-specific configuration. Search for omitBackground and set it to false for a white browser default.
Check the file type and extension. Puppeteer documents PNG as the default screenshot type. When path is supplied, the extension can determine the output type. Use a .png path when you intend to preserve transparency, and avoid mismatched extensions and explicit type values.
Check the image’s alpha channel. View the file in an image editor or viewer that shows transparent pixels distinctly. Some viewers display transparency against white, which can make a transparent image look white; others use a checkerboard or dark canvas. The option documentation does not specify how individual viewers render alpha.
Separate browser default from page CSS. If the site sets a background on the document or an element, inspect the page’s styles. omitBackground concerns the browser’s default white background; it is not a general CSS background-removal switch.
Record the runtime when behavior differs. Note the Puppeteer version, browser product and version, launch headless setting, screenshot options, output extension, and relevant page CSS. These details help distinguish a configuration issue from a browser-specific edge case.

4. Options that affect this problem

Option or detail	What to use	Why it matters
`omitBackground`	`false` for the default white browser background; `true` when transparency is wanted	This is the direct setting for whether Puppeteer omits its default white background. The documented default is `false`.
`type`	`'png'` for PNG; choose another supported format only when it fits your output needs	Puppeteer documents PNG as the default screenshot type. The output format affects whether an alpha channel can be represented.
`path`	Use an extension that matches the intended image format, such as `screenshot.png`	When a path is supplied, its extension can determine the screenshot type.
`headless` at launch	Record the mode used when investigating an unexpected result	A historical issue reported black output with `omitBackground: true` in non-headless mode. This report is a diagnostic clue, not a universal rule.
Browser product and version	Record the actual browser used by Puppeteer	Browser-specific behavior can matter. A historical Firefox issue reported a protocol error for the background override used with transparency.

Do not change several variables at once if you are trying to isolate an unexpected result. First make the screenshot option explicit, then verify the saved file type and inspect the page’s own background styles.

5. Troubleshooting

The PNG still appears transparent

Cause: A shared or conditional screenshot options object may still set omitBackground: true, or the viewer may be showing the file’s alpha channel in a way that looks transparent.

Fix: Set omitBackground: false directly on the final screenshot call. Inspect the saved file in a viewer that distinguishes transparent pixels, and confirm that the path and type agree.

The screenshot has a page-colored background rather than white

Cause: The page may paint its own background with CSS. The option only addresses Puppeteer’s default white background.

Fix: Inspect the document and relevant element styles. If you control the page and need a white capture, set its CSS background to white before capturing; do not expect omitBackground to remove page styling.

The result is black in non-headless mode

Cause: A historical Puppeteer issue report describes black output with omitBackground: true in non-headless mode. It does not establish that every version or setup behaves this way.

Fix: For a white result, set omitBackground: false. If transparency is required, record the Puppeteer and browser versions and headless setting, then compare behavior in the intended runtime.

Firefox reports an error about `Emulation.setDefaultBackgroundColorOverride`

Cause: A 2020 issue reported this protocol error when transparency was requested in Firefox. The issue was closed as not planned; it is historical evidence and may not describe current combinations.

Fix: Confirm your current Puppeteer and Firefox versions and whether your workflow requires transparency. If you need a white background, try omitBackground: false. Treat the old report as a compatibility clue, not a guarantee about current Firefox support.

The extension says PNG, but the file is another format

Cause: The screenshot type may be inferred from the path, or an explicit type may disagree with the extension.

Fix: Make both agree. For example, use path: 'screenshot.png' and type: 'png' when PNG output is intended.

6. Reliability, performance, and cost

This fix changes a screenshot option; it does not require a different capture workflow. For repeatable output, pin and record the Puppeteer and browser versions used by your application, keep the final screenshot options explicit, and make the output format unambiguous. When debugging, save the exact options and runtime details alongside the artifact.

The research for this issue does not establish performance differences between the background settings, provide benchmarks, or identify a particular cloud or browser cost. Do not assume that changing omitBackground changes capture speed or price. Measure those in your own runtime if they matter to your workload.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its API returns an image or PDF from one GET request. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

8. FAQ

Is a transparent screenshot always caused by `omitBackground: true`?

It is the first option to check, but also verify the saved format, alpha display, and whether the page itself paints a background.

Should I use PNG for a transparent screenshot?

Puppeteer documents PNG as the default screenshot type, and it is the format to use when you need to preserve transparency.

Does setting `omitBackground: false` force every page element to be white?

No. It requests the browser’s default white background. Page CSS can still paint its own backgrounds.

What details should I include when asking for help?

Share the final screenshot options, Puppeteer and browser versions, launch mode, output type and extension, and whether the page defines a background.

Sources

Puppeteer ScreenshotOptions API — option description, default, screenshot type, and path behavior.
Puppeteer issue #6974 — historical report involving non-headless mode and a black result with transparency enabled.
Puppeteer issue #4789 — historical Firefox protocol error report for the background override.