Cypress Screenshots Missing from CI: Troubleshooting Guide

If Cypress screenshots are missing from CI, check two separate things: whether Cypress created the screenshot on the runner, and whether your CI workflow uploaded that file as an artifact. Cypress normally captures screenshots for failed tests during cypress run. The default folder is cypress/screenshots. A screenshot on the runner is not automatically downloadable from every CI provider.

Start by checking the run mode and test result, then confirm the screenshot settings and folder, and finally inspect the artifact upload step. This sequence distinguishes a capture problem from a retention or path problem.

1. Confirm Cypress should have captured a screenshot

Automatic failure screenshots are associated with cypress run, not cypress open. They are taken when a test fails, so a passing run normally has no failure screenshot to upload. To capture a screenshot deliberately in a test, call cy.screenshot().

it('captures the page for later review', () => {
  cy.visit('/dashboard')
  cy.screenshot('dashboard-check')
})

Use a deliberate capture when you need evidence from a passing test or a particular point in a test. For automatic failure evidence, verify that the CI command actually runs Cypress in run mode and that the test failed.

2. Check the screenshot configuration and output directory

The relevant defaults are screenshotOnRunFailure: true and screenshotsFolder: 'cypress/screenshots'. A project setting, screenshot default, or runtime configuration override can change those values. Check the configuration that the CI runner actually uses, then inspect that directory on the runner after Cypress exits.

const { defineConfig } = require('cypress')

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

If the project uses another configuration format, keep the same option names and verify their effective values for the CI run. Also check whether the workflow runs Cypress from a different working directory than expected: a relative folder path is interpreted in the context of the project running Cypress.

3. Account for Cypress clearing the folder before a run

Cypress clears the contents of the configured screenshots folder before cypress run by default. The setting is trashAssetsBeforeRuns, which defaults to true. This can remove screenshots left by a previous run, so old files in a persistent workspace are not a reliable indication of what the latest run produced.

Set it to false only if retaining files across runs is intentional. Be aware that files from earlier runs can then be mistaken for current evidence unless your workflow separates or names the output by run.

4. Verify files on the runner before debugging upload

After the Cypress step, inspect the configured folder in the same job and workspace. If it contains no image files, troubleshoot capture first: confirm a test failed, screenshotOnRunFailure is enabled, the run used cypress run, and the effective screenshot folder is the one you inspected. If the file exists, capture succeeded; focus on artifact configuration and upload conditions.

Keep the two questions distinct:

No file on the runner: investigate run mode, test outcome, configuration, and output path.
File on the runner but no downloadable artifact: investigate upload ordering, path, conditions, and the CI provider’s artifact interface.

5. Upload screenshots as a GitHub Actions artifact

GitHub Actions requires an upload step that runs after Cypress and points to the actual screenshot folder. The example below follows the Cypress-maintained GitHub Action repository’s pattern. The failure condition is optional; use it when the artifact is only needed after a failed workflow. For diagnosis, warn makes a path with no matching files visible in the action log.

steps:
  - name: Cypress run
    uses: cypress-io/github-action@v7

  - name: Upload screenshots
    if: failure() # Optional: upload only when an earlier step failed
    uses: actions/upload-artifact@v7
    with:
      name: cypress-screenshots
      path: cypress/screenshots
      if-no-files-found: warn

Ensure the upload step is after the Cypress run, and change path if your configured screenshotsFolder differs. If you use a matrix, give each job a distinct artifact name so independent jobs do not contend for the same artifact name. Check the action log for a no-files-found message and look in the workflow run’s artifact area.

The upload action supports different behavior when no files match, including warning, error, or ignoring the condition. Cypress’s maintained example uses ignore; during troubleshooting, warn or error is more informative than silently ignoring a mismatch. Confirm action versions against the versions supported by your repository and runner when you configure the workflow.

6. Adapt the artifact step for other CI providers

The same workflow applies to CircleCI, GitLab CI, Jenkins, AWS CodeBuild, and other CI systems: preserve the runner’s screenshot directory and use that provider’s artifact mechanism. The GitHub Actions YAML above is provider-specific; do not paste it into another provider’s pipeline. Consult that provider’s current official artifact documentation for its syntax, retention behavior, and download location.

Cypress Cloud can also show screenshots from a CI run when the run is recorded and the project has the relevant Cloud setup. Test Replay can add execution context beyond a static image. These options depend on the project’s configuration; they do not automatically replace a provider-native artifact when your team needs a downloadable file in the CI interface.

7. Troubleshoot CI-only failures separately

A missing screenshot and a test that fails only in CI are related but separate problems. Once you know whether the screenshot exists on the runner, use the available run evidence to investigate the test failure itself. Compare the CI environment with local execution and inspect screenshots, video, or Test Replay where configured. Differences in environment can explain why a test fails, while the screenshot settings and artifact step explain whether evidence is saved and retained.

Common errors and fixes

Symptom	Likely cause	What to check or change
No screenshot after a passing run	Automatic screenshots are failure captures.	Use a failing test to verify automatic capture, or call `cy.screenshot()` at the point you want evidence.
No screenshot from `cypress open`	Automatic failure capture is documented for `cypress run`.	Run the CI command in run mode or add an explicit `cy.screenshot()`.
Failure occurred, but no file was created	`screenshotOnRunFailure` may be disabled or overridden.	Check the effective configuration and enable `screenshotOnRunFailure`.
Upload reports no files found	The artifact path does not match the configured folder, or no capture was created.	Inspect the runner’s output directory and align the upload path with `screenshotsFolder`.
Old screenshots disappeared	`trashAssetsBeforeRuns` clears the folder before a run by default.	Upload current output after the run. Disable cleanup only when retaining prior files is intentional.
File exists in logs or workspace but not in the run’s artifacts	No upload step ran, it ran before Cypress, or its condition skipped it.	Place the upload after Cypress, review its `if` condition, and confirm the CI provider shows the artifact.
Different CI matrix jobs overwrite or obscure evidence	Jobs use a non-unique artifact name.	Include the job or matrix identifier in the artifact name.
Screenshot is present but does not explain a CI-only failure	A static image shows state at capture time but not the full execution sequence.	Compare CI and local environments; use video or configured Cypress Cloud Test Replay for more context.

Performance, reliability, and artifact cost

Keep the upload focused on the screenshot directory so the workflow transfers only the evidence you need. Uploading after the test run preserves the files Cypress generated; a failure-only condition can avoid uploading screenshots on successful runs, but it also means there will be no artifact for a passing run unless you change the condition. For debugging a path mismatch, a visible no-files-found warning or error is more useful than ignoring it.

Artifact retention and access are controlled by the CI provider and project settings. The research sources do not establish a universal retention period or price, so check your provider’s current documentation and account configuration. If the team needs execution context rather than just image files, consider whether its existing Cypress Cloud setup provides the needed view.

Or skip the browser setup

If your task is to capture a web page for a report or workflow rather than debug Cypress’s test-runner output, ScreenshotNeo can return an image or PDF with one API request. It does not repair Cypress artifact uploading; it provides a separate screenshot capture path.

See the ScreenshotNeo API documentation for request options. Here is the one-call cURL example:

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

ScreenshotNeo 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 take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.

FAQ

Where are Cypress screenshots saved by default?

In cypress/screenshots, unless the project or runtime configuration changes screenshotsFolder.

Will a passing Cypress test create a failure screenshot?

No. Automatic run screenshots are for failures. Use cy.screenshot() when you want an intentional capture during a passing test.

Does Cypress automatically make screenshots downloadable in CI?

Do not assume so. Configure the CI provider’s artifact upload step and point it at the folder Cypress actually uses.

Should I turn off screenshot-folder cleanup?

Only when keeping earlier files is part of your workflow. By default, Cypress clears the folder before a run, so upload the current run’s output after Cypress finishes.