A blank Cypress screenshot can mean three different things: no screenshot file was saved, the page rendered without visible content, or the CI artifact viewer is showing the wrong or empty file. First locate the PNG in the configured screenshot folder, then compare the same test in headed and headless Chrome. Adjust viewport settings only if the evidence points to a size or scaling problem.
First identify what “blank” means
Check the configured screenshotsFolder; Cypress uses cypress/screenshots by default. Determine whether the expected PNG exists and opens as an image. If it does, inspect the page content in the image. If it looks correct locally but appears empty in CI, verify which file the artifact viewer received and when the workflow uploaded it. These are separate failure modes and need different fixes. Cypress documents screenshot capture and video behavior, while the cy.screenshot() API documentation covers the command.
No screenshot file exists
During cypress run, Cypress captures screenshots on test failure by default. The screenshotOnRunFailure setting controls this behavior. Confirm it has not been set to false, and check that your CI artifact step collects the configured screenshot directory rather than assuming a different path.
The file exists but the page is empty
The browser may have captured a genuinely blank or incomplete render. Reproduce the same test in headed Chrome and compare the final page state with the headless output before changing capture dimensions.
Recommended Free Tools
#1 Best Overall
The image is valid but the CI preview is blank
Check the artifact path, upload timing, and whether the workflow is displaying a current file. Cypress clears screenshot assets before a run by default, so an old path or artifact expectation may no longer match what the run produced.
Check Cypress capture settings and artifact handling
Review the effective Cypress configuration for these settings. Defaults below are documented by Cypress; project configuration can override them.
Rank #2
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL160_.jpg)
- Intuitive interface of a conventional FTP client
- Easy and Reliable FTP Site Maintenance.
- FTP Automation and Synchronization
| Setting | Documented default | What to check |
|---|---|---|
screenshotsFolder |
cypress/screenshots |
Make sure the run and artifact upload step use the same path. |
screenshotOnRunFailure |
true |
Confirm automatic failure screenshots have not been disabled. |
trashAssetsBeforeRuns |
true |
Cypress clears configured screenshots, videos, and downloads folders before a run; collect files produced by the current run. |
video |
false |
Enable video when you need to inspect the run leading up to a failure. |
See Cypress’s configuration reference for the full configuration and current options. A cy.screenshot() call is asynchronous and takes around 100 ms; if the application changes immediately before or after the call, the captured state may not be the state you expected. The Command Log can also render asynchronously, so an error appearing there may not be present in the screenshot.
Compare headed and headless Chrome with the same test
Cypress launches browsers headlessly by default when you run cypress run from the CLI. To watch the browser and inspect the command log and final application state, run:
npx cypress run --headed --no-exit --browser chromeUse the same test, application state, and relevant configuration for the headed and headless runs. If the headed screenshot is also blank, focus on application timing, test behavior, or the page itself. If only the headless capture is affected, investigate browser state, policy, version, and environment differences.
Investigate headless-specific causes
Chromium’s Cypress tab may be paused after opening a new tab
If the test opens a new tab—often through a link with target="_blank"—check whether the Cypress tab’s renderer has been paused. Cypress documents that Chromium will not capture screenshots while the Cypress tab renderer is paused; Cypress attempts to activate the tab during capture. Treat this as a targeted possibility when the test opens tabs, not as a general explanation for every blank screenshot. See the screenshot command documentation.
Browser extensions or enterprise policies may interfere
Restrictions on extensions can cause browser problems. If the issue occurs on a managed machine or CI image, check applicable Chrome policies and whether they affect the run. Cypress recommends considering Chrome for Testing when enterprise or group policies interfere; consult its configuration guidance.
A browser update or environment difference can change the result
Chrome is evergreen, so an update can break automated tests. When the symptom is version-sensitive, reproduce it with a pinned browser version rather than comparing runs made with different Chrome builds. For a meaningful visual comparison, keep the OS, fonts, browser version, viewport, and display-related settings as consistent as possible. Differences in these conditions can affect output. Cypress discusses screenshot and video resolution in its high-resolution screenshots and videos guidance.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Change dimensions only when size or scaling is wrong
Cypress documents a headless default viewport of 1280 × 720 and forces device pixel ratio (DPR) to 1. Those defaults affect screenshot and video dimensions; changing them is a resolution or scaling adjustment, not a proven cure for a completely blank page.
If the content is present but cropped, scaled unexpectedly, or rendered at the wrong size, Cypress shows how to change headless Chrome’s window dimensions and device scale factor through before:browser:launch. Use the launch event and options that match your installed Cypress version, then verify the output dimensions. For visual baselines, keep the environment and viewport fixed and pin the browser where practical. See Cypress’s browser-launch reference and resolution guidance.
Use this diagnostic order for a blank screenshot in CI
- Find the image. Check the configured
screenshotsFolder, which defaults tocypress/screenshots. Open the PNG rather than relying only on the CI preview. - Confirm capture is enabled. Check
screenshotOnRunFailureand the test result. For a manual capture, confirm the test reaches thecy.screenshot()call. - Check cleanup and collection. Because
trashAssetsBeforeRunsdefaults totrue, confirm the artifact step uploads the current run’s files from the configured folder. - Watch the run in headed mode. Use
npx cypress run --headed --no-exit --browser chromeand compare the same test with headless output. - Inspect tab behavior. If the test opens a new tab, investigate whether the Cypress tab’s Chromium renderer is paused during capture.
- Compare browser and machine conditions. Check Chrome version, OS, fonts, viewport, extensions, and enterprise policies; pin a browser version when reproducing a version-dependent failure.
- Tune dimensions last. Change viewport or DPR only when the captured content is present but its size or scaling is wrong.
Or skip the browser setup
If your goal is to capture a webpage rather than debug a Cypress test, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. For example, this cURL call saves a WebP screenshot of the target URL; replace the sample URL with the page you need and supply your API key. See the ScreenshotNeo API documentation for request options.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
