cypress screenshot on failure not captured: how to fix

TL;DR

Cypress only screenshots on failure, and only if the config switch is on and the folder is writable. Check screenshotOnRunFailure, check the folder, then check that CI actually uploads the folder. Most CI cases are captured-but-never-uploaded.

Problem

Cypress should save a screenshot automatically when a test fails, but the screenshots folder is empty after a failing run.

Steps

1. Confirm the run actually failed. Expected: Cypress only auto-captures on failure, never on passing tests.
2. Open cypress.config.js and check screenshotOnRunFailure is not set to false:

module.exports = {
  e2e: {
    screenshotOnRunFailure: true,
  },
}

Expected: the value is true or absent (true is the default).

1. Check the screenshotsFolder setting and confirm the folder is writable by the Cypress process. Expected: the folder exists or Cypress can create it, with write permission.
2. If the run uses retries, look for screenshots named with the attempt number. Expected: files like spec-name (failed).png exist for each failed attempt.
3. In CI, confirm the job uploads the screenshots folder as an artifact after the run. Expected: the artifact step runs even when tests fail, and the screenshots appear in the job artifacts.
4. Re-run a known-failing spec. Expected: a PNG lands in the screenshots folder.

When to use

• Failing runs produce no screenshot files
• Screenshots exist locally but not in CI artifacts
• You recently changed the Cypress config or the CI job steps

When not to use

• You want video of the run (enable video instead)
• You call cy.screenshot() yourself and it fails (check the call arguments)
• You want screenshots of passing tests (take them explicitly per test)

Tool compatibility

• Cypress 12 through 14, cypress run and cypress open
• PNG screenshots in the configured screenshotsFolder
• Any CI provider with an artifact upload step

Variant phrasings

Cypress not taking screenshots on test failure in CI

The screenshots are usually captured but never uploaded. Make the artifact step run on failure, not just on success.

Screenshot folder empty after failed Cypress run

Check screenshotOnRunFailure and folder write permissions before anything else.

Why it happens

Automatic screenshots are a run-failure hook with a config switch and a folder target. If the switch is off, the folder is not writable, or CI discards the folder before upload, the capture silently never lands anywhere you can see.

Edge cases

• Screenshots exist but show a blank page: the app had not rendered when the failure hit. That is a timing problem in the test, not a screenshot problem.
• Only some failures capture: failures inside after hooks or from uncaught app exceptions can skip the hook. Check the failure type.
• Huge screenshot folders in CI: old runs accumulate. Clean the folder at the start of the job.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iUbNIl-HgZA24t-544JwcA