Cypress Screenshot Not Saved After a Failed Test: Fix

If Cypress does not save a screenshot after a test fails, first run the test with cypress run, then confirm that the effective configuration has screenshotOnRunFailure: true. Look in the configured screenshotsFolder—by default, cypress/screenshots—including the spec’s subfolders. If the screenshot exists locally but disappears after CI finishes, configure that CI job to retain or upload the folder. Cypress does not automatically capture failure screenshots in cypress open, and a normal cypress run clears asset folders before running unless configured otherwise. Cypress screenshot and video guide

1. Confirm Cypress is running in the right mode

Automatic screenshots on test failure are produced during cypress run, including headless and CI runs. Cypress does not automatically capture failure screenshots during interactive cypress open. To check the behavior, run the failing spec from a terminal:

npx cypress run --spec "path/to/spec.cy.js"

Replace the example path with the path to your spec. If this command saves the image but cypress open does not, that is the expected difference between the two modes. To save an image deliberately while debugging interactively, call cy.screenshot() in the test; that is a manual capture and does not establish whether automatic failure capture is enabled. Cypress cy.screenshot() reference

2. Check the configuration Cypress actually loads

The documented default for screenshotOnRunFailure is true. Still, a project configuration or command-line override may change the effective value. If the run uses --config-file, check that file rather than assuming Cypress loaded the root config. The CLI also accepts --config overrides. Cypress configuration reference · Cypress CLI reference

JavaScript configuration

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  screenshotOnRunFailure: true,
  screenshotsFolder: 'cypress/screenshots',
})

TypeScript configuration

import { defineConfig } from 'cypress'

export default defineConfig({
  screenshotOnRunFailure: true,
  screenshotsFolder: 'cypress/screenshots',
})

Use the configuration shape appropriate for your installed Cypress version and testing type. If your project uses a non-default config file or version-specific structure, verify the active file and its supported options in the Cypress reference. Configuration options

3. Find the screenshot in the configured folder

The default output directory is cypress/screenshots, but screenshotsFolder can change it. Cypress organizes screenshots beneath folders associated with the spec. Automatic failure screenshot names are based on the test name and end with (failed).png. With retries, look for attempt markers as well. Screenshot output and naming · Cypress test retries

# From the project root, list screenshot files (macOS/Linux)
find cypress/screenshots -type f -name '*.png' -print

If the folder is configured elsewhere, substitute that path. Check the nested spec directories and search for the test name, (failed), or retry attempt markers rather than expecting every image directly inside the root screenshot folder.

4. Account for cleanup between runs

Cypress clears the contents of its downloads, screenshots, and videos folders before each cypress run when trashAssetsBeforeRuns is true, which is the default. This means an earlier run’s screenshot may disappear when the next run starts. If you need to keep earlier run artifacts in the working directory, set the option to false in the active configuration:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  screenshotOnRunFailure: true,
  screenshotsFolder: 'cypress/screenshots',
  trashAssetsBeforeRuns: false,
})

Keeping assets across runs can make it harder to tell which run created a file. In CI, a reliable approach is usually to upload the current run’s screenshot folder before the job ends, using the artifact mechanism provided by that CI system. The exact upload syntax depends on the CI provider. Cypress saving a file to the job’s filesystem does not itself configure retention after the job ends. Cypress configuration reference

5. Test whether the output path is writable

Add a manual screenshot at a useful point in the test, then check whether it appears beneath the configured screenshot folder:

cy.screenshot('debug-check')

This can help determine whether the configured path is reachable and whether Cypress can write a screenshot. A successful manual screenshot does not prove that automatic failure capture is enabled; check the run mode and effective screenshotOnRunFailure value separately. Cypress screenshot command

6. Preserve screenshots in CI

When a screenshot is present during a job but unavailable afterward, check the CI job’s artifact and workspace behavior. Make sure the job uploads the configured screenshot directory after Cypress runs, and that the upload step still runs when tests fail. Confirm that the artifact path matches the effective screenshotsFolder, especially if the project overrides the default. These are CI workflow checks: Cypress writes the local file, while the CI system determines whether it remains accessible after the job.

1. Run Cypress and note the effective screenshot folder.
2. Configure the CI artifact step to include that folder.
3. Ensure the artifact step executes after a failed test run.
4. Open the resulting artifact and verify it contains the spec’s nested screenshot path.

The configuration syntax varies by CI provider, so use that provider’s artifact documentation for the upload step. Avoid relying on a later job to read files from an earlier job unless the workflow explicitly transfers or retains them.

Common causes and fixes

Symptom	Likely cause	What to check or change
No automatic failure image in an interactive session	The test ran with cypress open.	Use npx cypress run --spec "path/to/spec.cy.js" to check automatic failure capture.
No image after a headless run	The effective config may disable failure capture, or Cypress may load a different config file.	Check screenshotOnRunFailure, any --config override, and any --config-file argument.
The screenshot folder is empty or unexpected	The output directory may be customized, or the image may be nested under a spec folder.	Check screenshotsFolder and search its subfolders for (failed).png.
An older screenshot vanished after another run	Cypress clears asset folders before a run by default.	Set trashAssetsBeforeRuns: false if earlier local artifacts must remain, or preserve each run’s artifacts separately.
The file exists during CI but not after the job	The CI workflow did not retain or upload the job’s local screenshot folder.	Add an artifact upload step for the configured folder and ensure it runs after test failure.
A manual screenshot works but the failure image does not appear	Manual capture and automatic failure capture are separate behaviors.	Verify cypress run mode and screenshotOnRunFailure independently.
Several images appear for a retried test	Retries can produce screenshots with attempt markers.	Inspect all files for the spec and test, including attempt suffixes; use the retry guide to understand the run configuration.

Reliability and runtime considerations

For a reproducible check, use the same Cypress command, config file, and working directory as the failing CI run. A local run using a different config can save screenshots successfully while the CI invocation does not. Record the effective output directory and preserve the folder as a job artifact when results must be inspected later. Cypress’s documented behavior covers automatic capture in cypress run, configurable capture and output settings, and cleanup before runs; artifact persistence is controlled separately by the CI workflow. Cypress screenshots and videos · Configuration reference

Screenshot capture adds work to a failing run, and retaining many runs’ folders can consume workspace or artifact storage. Keep the artifacts needed to investigate failures and apply the retention policy offered by your CI system. The provided Cypress documentation does not give a universal runtime or storage benchmark, so measure those costs in your own workflow if they matter.

Or skip the browser setup

If the goal is a screenshot of a page rather than a Cypress failure artifact, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. 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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

These examples capture a page through the API; they do not replace Cypress’s test-run failure hook or its spec-linked failure artifacts. See the API options and response details, then sign up for 1,000 free screenshots a month with no card.

FAQ

Does Cypress take a failure screenshot during cypress open?

No. Automatic failure screenshots are a cypress run behavior. Use cy.screenshot() when you want to capture an image manually during debugging. Cypress screenshot guide

What is the default screenshot folder?

cypress/screenshots. A project can change it with screenshotsFolder. Configuration reference

Why is there a (failed).png suffix?

Cypress uses a failure suffix for automatic failure screenshots. Retries can add attempt markers, so check the spec’s nested directory for related files. Test retries

Will changing trashAssetsBeforeRuns keep CI screenshots after the job?

No. It controls cleanup of local asset folders before Cypress runs. Configure your CI workflow to retain or upload the screenshot folder if it must be available after the job.