How to Fix Cypress Chrome Browser Not Available
Fix Cypress’s “Chrome is not available” error by checking detection, paths, Linux dependencies, CI displays, policies, and browser connectivity.
Cypress shows Chrome is not available when it cannot find a supported Chrome-family executable in the environment where Cypress is running. The fastest fix is to inspect detection, install or select a browser in that same environment, pass the browser’s executable path when auto-detection misses it, and then resolve Linux display, library, policy, or extension restrictions.
Cypress automatically detects installed browsers, so configuration is normally unnecessary. Detection can fail when the browser is missing from a container or CI runner, the binary has a nonstandard name, the installation is portable, or Chrome launches but Cypress cannot connect to it. The commands below cover each case.
1. Confirm what Cypress detects
Run these commands from the project and environment that execute your tests:
npx cypress info
DEBUG=cypress:launcher:* npx cypress infoThe first command lists the browsers Cypress found. The debug form adds launcher diagnostics. Look for Chrome, Chrome for Testing, Chromium, or Edge. Cypress documents that it detects browsers installed on the operating system automatically (browser detection documentation).
If Chrome appears in the list, try selecting it explicitly:
npx cypress open --browser chrome
npx cypress run --browser chromeFor a reproducible CI browser, use Chrome for Testing:
npx cypress run --browser chrome-for-testingChromium and Edge are also valid Chrome-family choices:
npx cypress run --browser chromium
npx cypress run --browser edge2. Install the browser in the environment that runs Cypress
A browser installed on your laptop is not available inside a container, remote VM, or CI runner unless that environment installs it too. Install Chrome, Chrome for Testing, or Chromium in the runner, or use a Cypress browser image that already contains the required browser.
After installation, verify from the same user and machine:
npx cypress info
npx cypress run --browser chromeChrome for Testing is usually the best automation target because its version can be pinned. Regular Chrome is convenient but can auto-update or be restricted by enterprise policy. Chromium is useful when Chrome-specific policy or extension behavior interferes. Electron is bundled with Cypress, but it is deprecated as a Cypress test browser.
3. Bypass auto-detection with the executable path
Pass the full path when the browser is portable, installed outside a standard location, or uses a name Cypress does not recognize:
npx cypress open --browser /usr/bin/chromium
npx cypress run --browser /usr/bin/chromiumOn Linux, Cypress checks names such as google-chrome, google-chrome-stable, chrome, chromium-browser, and chromium. If your distribution uses another filename, either pass its absolute path or create a symlink with one of those expected names.
On macOS, a standard Google Chrome executable is:
/Applications/Google Chrome.app/Contents/MacOS/Google ChromeChrome for Testing and Chromium may need to be moved into /Applications before Cypress detects them automatically. Passing the executable path avoids relying on bundle discovery.
4. Install Linux runtime libraries and a virtual display
In headless Linux CI, Chrome can be installed and detected yet fail immediately because graphics, sound, NSS, X11, notification, or virtual-display libraries are missing. On Ubuntu or Debian, install the documented runtime packages:
apt-get update
apt-get install -y libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfbUbuntu 24.04 and Debian 13 may provide the t64 package variants, including libgtk-3-0t64, libgbm-devt64, and libasound2t64. Use the package names available for your distribution.
When your CI job needs an X server, run Cypress under Xvfb:
xvfb-run --auto-servernum npx cypress run --browser chromeIf your CI image already starts Xvfb, do not start a second display. Check the job logs for the configured DISPLAY value.
5. Distinguish detection errors from connection errors
“Chrome is not available” means Cypress did not select a usable browser. A different failure occurs when Chrome is detected and launched but Cypress cannot connect to the Chrome DevTools Protocol. Typical symptoms include a startup timeout or ECONNREFUSED.
Check Chrome policy
Open chrome://policy in the affected Chrome installation and inspect RemoteDebuggingAllowed. It must be undefined or set to true. A restrictive enterprise policy can allow Chrome to launch while blocking the connection Cypress needs. Chrome for Testing or Chromium is often cleaner in CI because Chrome-branded enterprise policies generally do not apply to them.
Allow the Cypress extension
Cypress uses a Chrome extension. If company security policy blocks extensions, ask an administrator to allow extension ID caljajdfkjjjdehjdoimjkkakekklcck. Without it, the browser may open but the test runner cannot complete setup.
Skip preference-file access when security tooling interferes
Security software that encrypts or locks Chrome’s user-data directory can prevent Cypress from reading or writing preferences. Try:
IGNORE_CHROME_PREFERENCES=1 npx cypress run --browser chromeThis tells Cypress to skip its Chrome preference-file access.
6. Repair the Cypress binary and cache
A damaged Cypress download or stale cache can look like a browser launch problem. Clear the cache, reinstall the binary, and rerun detection:
npx cypress cache clear
npx cypress install
npx cypress infoCypress requires cypress install after the cache is cleared. In CI, make sure the install step runs in the same job image and user context as the test command.
7. Use a CI checklist
- Run
npx cypress infoinside the runner, not on a developer workstation. - Enable
DEBUG=cypress:launcher:*while diagnosing detection. - Pin Chrome for Testing when browser version reproducibility matters.
- Install GTK, GBM, NSS, ALSA, X11, notification, and Xvfb dependencies on Linux.
- Use
xvfb-runwhen the runner has no display. - Pass an absolute executable path for portable or custom browser installs.
- Check
chrome://policyforRemoteDebuggingAllowed. - Confirm security tooling allows the Cypress extension and Chrome profile writes.
- Clear and reinstall the Cypress binary if its cache is damaged.
8. Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
Chrome is not available and no Chrome appears in cypress info |
Browser is not installed in the current environment | Install Chrome, Chrome for Testing, or Chromium in the runner; rerun npx cypress info. |
| Browser is installed but absent from the list | Nonstandard executable name or portable location | Pass the absolute path with --browser, or create a symlink using a recognized name. |
| Chrome appears but startup times out | Missing Linux libraries, no display, or a blocked DevTools connection | Install runtime packages, run under Xvfb, and check RemoteDebuggingAllowed. |
ECONNREFUSED after Chrome launches |
Chrome policy or security tooling blocks remote debugging | Allow remote debugging, try Chrome for Testing or Chromium, and inspect enterprise controls. |
| Extension installation fails | Company policy blocks the Cypress extension | Allow extension ID caljajdfkjjjdehjdoimjkkakekklcck. |
| Preferences cannot be read or written | Encrypted or locked Chrome user-data directory | Set IGNORE_CHROME_PREFERENCES=1. |
| Failure begins after Cypress cache cleanup | Cypress binary was removed and not reinstalled | Run npx cypress install. |
9. Choose the right browser for the job
| Browser | Best fit | Trade-off |
|---|---|---|
| Chrome for Testing | Repeatable local and CI automation | Requires managing a pinned browser version. |
| Regular Chrome | Convenient desktop development | Auto-updates and enterprise policy can change behavior. |
| Chromium | CI or environments affected by Chrome policy | May require explicit installation and path configuration. |
| Edge | Microsoft-managed environments | Still depends on correct installation and CI libraries. |
| Electron | Quick bundled runs | Deprecated as a Cypress test browser. |
10. Performance and reliability notes
Browser startup is usually the slowest part of a Cypress job. Reusing a CI image with the browser and libraries preinstalled avoids repeated package installation. Pinning Chrome for Testing reduces failures caused by an automatic browser update. Keep the browser and Cypress versions compatible with the versions supported by your project, and collect npx cypress info output whenever a runner changes.
Cypress retries the Chrome DevTools Protocol connection for up to 50 seconds before failing. A timeout that lasts roughly that long points toward a connection, policy, display, or dependency problem rather than simple browser detection. Capture the full error, operating system, Cypress version, browser flavor, executable path, CI image, and debug output before escalating.
Or skip the browser setup
If your goal is to generate website screenshots rather than run an interactive Cypress test, ScreenshotNeo provides a direct screenshot API. It handles the browser environment for you, so there is no Chrome binary, Xvfb setup, or Cypress launcher to maintain.
One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed. Its MCP server gives Claude, Cursor, and other MCP clients take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account and start with 1,000 screenshots per month at no charge.
FAQ
Why does Cypress find Chromium but not Chrome?
The Chrome executable may be missing, renamed, installed outside a standard path, or blocked by the environment. Use npx cypress info, then pass the exact executable path with --browser.
Should CI use regular Chrome or Chrome for Testing?
Prefer Chrome for Testing when reproducibility matters because its version can be pinned. Regular Chrome can auto-update or inherit enterprise policy.
Can I fix this only by changing Cypress configuration?
Usually no. The browser must exist and be launchable in the runner. Configuration can select a browser or path, but it cannot supply missing operating-system libraries, displays, or permissions.
What information should I include in a bug report?
Include the complete error, OS and CI image, Cypress version, browser flavor and version, executable path, npx cypress info, and output from DEBUG=cypress:launcher:* npx cypress info.
