Cypress Troubleshooting Guide

Cypress wonโ€™t start

Canโ€™t run because youโ€™ve entered an invalid browser name
Can't run because you've entered an invalid browser name. Browser: Replay Chromium was not found on your system or is not supported by Cypress. Cypress supports the following browsers: - electron - chrome - chromium - chrome:canary - edge - firefox You can also use a custom browser: https://on.cypress.io/customize-browsers Available browsers found on your system are: - chrome - chromium - firefox - firefox:dev - firefox:nightly - electron - Replay Firefox
  • This is expected (for now). Check first whether the process exits immediately, chances are the test ends up proceeding as expected!
  • While modifying cypress.config.js, make sure youโ€™re returning the config object in setupNodeEvents
  • Make sure youโ€™re using the correct browser for your operating system. replay-chromium is only supported on linux, whereas replay-firefox supports both mac and linux.
  • The environment variable CYPRESS_INSTALL_BINARY may be suppressing the browser install step. If itโ€™s set to 0, make sure to add an explicit workflow step to install the browsers (npx @replayio/cypress install)
  • Your caching strategy might be keeping our plugin from pulling in the correct browser. Start debugging it by turning off all caching, e.g. actions/cache

How do I use Replay with versions earlier than 10.9?

Replay works best with Cypress 10.9 or later but can be used with Cypress 8 or later with some additional environment configuration:
  • RECORD_ALL_CONTENT must be set when using replay-firefox to record replays
  • RECORD_REPLAY_METADATA_FILE must be set for either browser to capture metadata about the test run.
When running locally, you can set these variables in your npm scripts so they are set every time:
"scripts": { "test:cypress": "cypress run", "test:cypress:replay": "RECORD_ALL_CONTENT=1 RECORD_REPLAY_METADATA_FILE=/tmp/replay-metadata cypress run" }
On CI, you can set these environment variables on the task that runs your tests:
# Install NPM dependencies, cache them correctly # and run all Cypress tests - name: Cypress run uses: cypress-io/github-action@v5 with: browser: replay-chromium env: RECORD_ALL_CONTENT: 1 RECORD_REPLAY_METADATA_FILE: /tmp/replay-metadata

Replay browser runs but doesnโ€™t record

The Replay browser is compiled against OpenSSL 1.1 which has been deprecated and is not included on some more recent platforms. To manually install it, run the following:
wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb


If youโ€™re using DeploySentinel, you may notice that either you are unable to record replays or the replays created do not show the Cypress Panel when you open them. This is often caused by conflicts between Cypress event handlers between two plugins.
We recommend wrapping Cypressโ€™ on method with our wrapOn adapter to address these integration issues. The wrapper adds support for multiple event handlers for each Cypress event as well as cascading return data to each handler.

Browser Hangs

When the browser hangs while running a test, it is likely an interaction between the test and our browser recording features. In that case, itโ€™s helpful to run the test in diagnostic mode which will run the test in a variety of scenarios with different browser features enabled.
You can run the test in diagnostic mode by passing in a mode flag.
npx @replayio/cypress run --mode diagnostics --level full
For more information, see
We also recommend going for the simplest reproduction which includes running the fewest specs possible and setting a timeout so that the test fails as soon as possible.
You can use the Cypress timeout command to set a timeout
describe("test spec", () => { it("test case", () => { // set the timeout to 1min cy.visit("/login", { timeout: 60000 }); }); });
You can set a single spec to run, by using the --spec flag
npx @replayio/cypress run --mode diagnostics --level full --spec tests/logout.spec.ts

Providing us with Logs

Add the following environment variables to your CI run:
  • DEBUG: cypress:launcher:browsers

Minimizing test runtime overhead

Add the following environment variables when running Cypress with Replay Chromium to turn off diagnostics and get a true read on the runtime overhead.

Metadata doesnโ€™t match replay content

The @replayio/cypress plugin uses metadata to link up a replay with the test result from cypress. If youโ€™re running your cypress tests in parallel on the same machine, you might encounter issues where the tests listed in the cypress panel do not match the replay content itself.
This is sometimes caused by the metadata from one test being overwritten by a second when running in parallel. In general, this can be fixed by setting RECORD_REPLAY_METADATA_FILE to a valid, unique path when starting cypress run. The mktemp is a good utility for this:
RECORD_REPLAY_METADATA_FILE=$(mktemp) npx cypress run --browser replay-chromium