Troubleshooting
What you'll learn
- Resources to help you troubleshoot Cypress App issues
- Common steps to isolate and resolve problems
Start here
There are times when you will encounter errors or unexpected behavior with Cypress itself. This guide recommends some resources and steps to take to troubleshoot those problems.
Update Cypress
We always recommend using the latest version of the Cypress App. If you're not using the latest version, upgrade to the latest version. Your issue may already be resolved.
Support channels
Check these support resources for Cypress App issues:
- Connect with our community in Discord
- Search existing GitHub issues
- Search this documentation (search is in the top right) 😉
- Search Stack Overflow for relevant answers
- If you still haven't found a solution, open an issue with a reproducible example.
If your organization signs up for one of our paid plans, you can get dedicated email support, which gives you one-on-one help from our team.
Isolate the Problem
When debugging a failing test, follow these general principles to isolate the problem:
- Look at the screenshots, video, or Test Replay of the test. Test Replay will show you the exact steps that were taken during the test including console logs and requests.
- Split large spec files into smaller ones.
- Split long tests into smaller tests.
- Run the same test in different browsers to isolate the problem to a specific browser.
- Run the same test in different environments (local, CI, etc.) to isolate the problem to a specific environment.
- Reduce the test to the smallest possible test that still reproduces the problem.
Troubleshooting Steps
Below are some steps you can take to troubleshoot common issues with Cypress.
Clear Cypress cache
If you're having an issue during installation of Cypress, try removing the contents of the Cypress cache.
This will clear out all installed versions of Cypress that may be cached on your machine.
cypress cache clear
After running this command, you will need to run cypress install
before
running Cypress again.
- npm
- yarn
- pnpm
npm install cypress --save-dev
yarn add cypress --dev
pnpm add --save-dev cypress
Allow the Cypress Chrome extension
Cypress utilizes a Chrome extension in order to run properly. If you or your company block specific Chrome extensions, this may cause problems with running Cypress. You will want to ask your administrator to allow the Cypress extension ID below:
caljajdfkjjjdehjdoimjkkakekklcck
You can check the current company policies for your Chrome installation by typing chrome://policy
into the address bar and pressing Enter.
Allow Cypress URLs on VPNs
To send the data and results of your tests to Cypress Cloud, Cypress needs free access to some URLs.
If you are running the tests from within a restrictive VPN you will need to allow some URLs so that Cypress can have effective communication with Cypress Cloud.
The URLs are the following:
https://api.cypress.io
- Cypress APIhttps://assets.cypress.io
- Asset CDN (Org logos, icons, videos, screenshots, etc.)https://authenticate.cypress.io
- Authentication APIhttps://capture.cypress.io
- Cypress Test Replayhttps://s3.amazonaws.com/capture.cypress.io
- Uploading Cypress Test Replay from Test Runnerhttps://cloud.cypress.io
- Cypress Cloudhttps://docs.cypress.io
- Cypress documentationhttps://download.cypress.io
- CDN download of Cypress binaryhttps://on.cypress.io
- URL shortener for link redirects
If you are using GitHub Enterprise or GitLab for Enterprise (Self-managed), you may also need to add the following to the version control IP allowlist:
3.211.102.119
- Dedicated IP18.213.72.78
- Dedicated IP35.169.145.173
- Dedicated IP44.199.152.70
- Dedicated IP52.70.95.89
- Dedicated IP
Clear App Data
Cypress maintains some local application data in order to save user preferences and more quickly start up. Sometimes this data can become corrupted. You may fix an issue you have by clearing this app data.
To clear App Data
- Open Cypress via
cypress open
- Go to
Developer Tools
->View App Data
- This will take you to the directory in your file system where your App Data
is stored. If you cannot open Cypress, search your file system for a
directory named
cy
whose content should look something like this:
📂 production
📄 all.log
📁 browsers
📁 bundles
📄 cache
📁 projects
📁 proxy
📄 state.json
- Delete everything in the
cy
folder - Close Cypress and open it up again
Print DEBUG logs
Cypress utilizes the debug module.
That means you can receive helpful debugging output by running Cypress with a system-level environment variable DEBUG
set to cypress:*
prior to running cypress run
or cypress open
.
Enabling debug output can generate a large amount of data. This may also impact performance. Only enable debug output when you need it.
To reduce the amount of debug output data generated, replace cypress:*
using a more selective value for DEBUG
.
See below, including the section Log sources.
If you need to share debug output collected in a file, consider first compressing it with a ZIP utility or similar to reduce the file size before sharing.
On macOS, Linux or Windows (Git Bash):
- npm
- Yarn
- pnpm
DEBUG=cypress:* npx cypress run
DEBUG=cypress:* yarn cypress run
DEBUG=cypress:* pnpm cypress run
You can change run
to open
in the above to capture debug logs when starting your tests from the Cypress Specs UI.
For non-POSIX type shells on Windows, set the DEBUG
environment variable as follows. (Replace npx
with yarn
or pnpm
if you are using Yarn or pnpm package managers instead of npm.)
On Windows CMD:
set DEBUG=cypress:*
npx cypress run
On Windows PowerShell:
$env:DEBUG='cypress:*'
npx cypress run
If you have issues with the logs not printing, it may be a permissions issue with setting the environment variable in your terminal. You may need to run your terminal in administrative mode or review your permission settings.
How to run Cypress CLI commands provides background information on running Cypress from the command line and includes a reference of additional command line options.