Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

The usual fix is to install the Cypress application binary explicitly and persist the same cache directory between GitLab jobs. The npm package and the executable are separate: a successful npm ci can leave you with Cypress JavaScript files but no downloaded binary. Check the cache path and installed version, run npx cypress install when lifecycle scripts were skipped, and make every job use the same CYPRESS_CACHE_FOLDER. If the binary is present but will not start, switch to Linux shared-library troubleshooting instead of reinstalling it.

What “A Cached Cypress Binary Could not be found” means

Cypress Documentation describes this error as a CI invocation of cypress run or cypress verify without a valid Cypress binary cache. The package installed from npm, Yarn, pnpm or Bun is not the complete desktop application. Its installation lifecycle hook normally downloads a platform-specific binary into a global cache. Your GitLab runner must either download that binary in the current job or restore a previously saved cache.

Typical causes are:

  • Lifecycle scripts were disabled with --ignore-scripts, package-manager policy, or security settings.
  • CYPRESS_INSTALL_BINARY=0 intentionally prevented the download.
  • The install job saved one directory while the test job restores another.
  • GitLab cache keys or policies caused a miss, so the test job starts without the binary.
  • A cached node_modules directory bypassed the package-manager install step and its postinstall hook.
  • The matching Cypress version is absent even though a different version is cached.

These are cache or installation failures. A different class of problem occurs when the expected executable exists but crashes because the Linux image lacks a required shared library.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Diagnose the job before changing the pipeline

1. Print the cache location

Run these commands in the same image and user context as the failing GitLab job:

#1 Best Overall
Sale
BONTEC Mobile Standing Desk with Keyboard Tray, Mobile Podium on Wheels
  • ADJUSTABLE HEIGHT DESIGN: The mobile standing desk promotes a healthier workstyle by allowing quick transitions between sitting and standing. The gas spring lift smoothly adjusts the height from 28.3in to 44in, supporting better posture and reducing neck and back strain during long working hours. This portable desk improves daily comfort and productivity across different environments.
  • SUPERIOR STABILITY AND DURABILITY: The rolling desk adjustable height model stands out with its sturdy H shaped steel base and reinforced structure, providing stability even at maximum extension. The waterproof and scratch resistant MDF desktop ensures long lasting use, while the retractable keyboard tray and hook create organized storage for accessories. This unique design differentiates the desk from standard folding table or rolling podium options on the market.
  • ERGONOMIC AND FUNCTIONAL DESIGN: The portable standing desk offers a spacious 25.6 x 17.7in surface to accommodate a laptop, monitor, or books. A dedicated slot holds phones and tablets, while the 23.6 x 11.8in keyboard tray supports a full size keyboard and mouse. The thoughtful structure allows the small standing desk to serve as a side table, study cart, or computer desk with keyboard tray in living rooms, bedrooms, and offices.
  • EASY MOBILITY WITH LOCKABLE WHEELS: The adjustable rolling desk includes four caster wheels that allow smooth movement between rooms. The lockable function secures the desk in place when needed, creating flexibility for use as a rolling laptop desk, classroom furniture, or teacher standing desk. The compact rolling table design makes the desk on wheels easy to move, while maintaining stability during presentations or study sessions.
  • EASY OPERATION AND LOW MAINTENANCE: The sit stand desk is operated with a simple hand lever that activates the gas spring for smooth upward adjustment, while gentle pressure lowers the surface. The mobile desk workstation requires minimal maintenance, as the MDF board is waterproof, scratch resistant, and easy to clean with a damp cloth. This reliable raising desk minimizes user effort and ensures long term durability without complex upkeep.
npx cypress cache path
npx cypress cache list

On Linux, the default is usually ~/.cache/Cypress. The list shows which binary versions are actually present. Compare that value with the Cypress version in the installed project package (for example, the version resolved by your lockfile). A cache containing another version does not satisfy the test.

2. Check install-script policy

Inspect the install command and CI variables for --ignore-scripts, disabled lifecycle scripts, or CYPRESS_INSTALL_BINARY=0. The latter is an explicit instruction not to download the binary. If your organization disables scripts globally, keep that policy for dependency installation and add a deliberate Cypress install step afterward.

3. Test an explicit install with logs

npx cypress install
npx cypress verify

For download, extraction, or permission details, rerun:

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
DEBUG=cypress:cli* npx cypress install

If this command cannot download the file, investigate runner network egress, proxy settings, disk space and permissions. If it succeeds but verify fails with missing libraries, follow the runtime branch below.

Rank #2
Sale
HUANUO 32x19 Inch Small Electric Standing Desk, Adjustable, Light Walnut
  • 【32” x 19” Perfect for Small Spaces & Corner】 Specially designed with a compact 32" x 19" desktop, this small electric standing desk seamlessly fits into limited areas like apartments, bedrooms, and cozy home office corners without crowding your room. It is the ultimate space-saving, height-adjustable solution to pair with under-desk treadmills and walking pads for remote workers, freelancers, and students
  • 【4 Memory Presets & DIY Wheel Ready】 This adjustable desk features a smart control panel with 4 programmable memory presets for effortless one-touch height adjustment (28.3" to 46.5"). Plus, built-in universal M8 screw holes on the desk feet allow you to easily install your own casters/wheels to DIY it into a mobile rolling desk.
  • 【176 lbs Max Load & Rounded Safety Corners】 Constructed with heavy-duty steel rails and a solid desktop, this small stand up desk supports up to 176 lbs with exceptional stability while transitioning. The tabletop features smooth rounded corners to protect you, your family, or pets from accidental bumps in tight, compact spaces.
  • 【Rigorously Tested for Long-Lasting Use】 Engineered for daily reliability, our motor and lifting system have been rigorously tested to withstand up to 50,000 lift cycles under full capacity. Enjoy a whisper-quiet, smooth sit-to-stand transition that keeps you focused and productive all day.
  • 【Easy Assembly & Budget-Friendly Choice】 Comes with detailed instructions and all hardware included for a hassle-free, quick setup. Get premium electric sit-stand functionality at an unbeatable, budget-friendly price. Risk-free purchase with dedicated customer support ready to help.

Use one cache path in every GitLab job

The safest arrangement is a project-local directory whose value is declared globally. Cypress’s GitLab example uses a shared CYPRESS_CACHE_FOLDER and caches that directory for worker jobs. The exact cache key and policy must match your runner and branch strategy, but the path must be identical when installing and running.

stages:
  - install
  - test

variables:
  CYPRESS_CACHE_FOLDER: "$CI_PROJECT_DIR/cache/Cypress"
  npm_config_cache: "$CI_PROJECT_DIR/cache/npm"

cache:
  key:
    files:
      - package-lock.json
  paths:
    - cache/Cypress/
    - cache/npm/

audit_install:
  stage: install
  image: cypress/browsers:latest
  script:
    - npm ci
    - npx cypress install
    - npx cypress verify
    - npx cypress cache path
    - npx cypress cache list

cypress_tests:
  stage: test
  image: cypress/browsers:latest
  script:
    - npx cypress verify
    - npx cypress run

Use the browser image and tag appropriate for your project; the example demonstrates cache flow, not a promise that every runner image behaves identically. The install job must save the directory and the test job must restore it before verify or run. If your GitLab configuration uses separate cache definitions per job, repeat the same path and compatible key in both places.

Cache policy and key checks

  • Confirm the install job ends successfully before the test jobs start.
  • Look in the job log for cache restore and save messages; a “cache not found” message is expected on a first run but not on a later run with the same key.
  • Include the lockfile in the key, or otherwise change the key when the Cypress version changes, so an old binary is not mistaken for the new one.
  • Ensure the runner user can read and execute files under the cache directory.
  • Do not assume caches are guaranteed storage. Keep npx cypress install in the install job so a cold cache repairs itself.

Why caching node_modules alone fails

Cypress warns that directly caching node_modules can bypass package-manager checks and leave the binary postinstall step unrun. A restored dependency tree may therefore contain the npm package but no application binary. Prefer your package manager’s download cache plus the dedicated Cypress binary cache. If you do cache dependencies for speed, still make the Cypress cache explicit and run npx cypress install as an idempotent step.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When using Yarn, pnpm or Bun, invoke Cypress through that project’s package-manager prefix, and apply the same lifecycle-script checks. The principle is unchanged: install the package, permit or replace its binary download step, and persist the resulting Cypress cache.

Rank #3
Dell Optiplex 3060 Desktop Computer | Intel i5-8500 (3.2) | 32GB DDR4 RAM | 1TB SSD Solid State | Built in WiFi | Bluetooth | Windows 11 Professional | Home or Office PC (Renewed)
  • [INTEL POWERED CONTENT] - Built with a 8th Generation Hexa-Core Intel i5 and 32GB of DDR4 RAM; Modern, Windows 11 ready, with 4K support, Executive multitasking, media streaming and smooth, multi-tab web browsing; Perfect as an all-purpose multimedia computer; built for content creators; Plenty of RAM and Mass storage for photo and video editing powered by Intel HD 630
  • [LATEST WIRELESS TECH] - This Dell Desktop Computer easily connects to the internet through the Built In WiFi / Bluetooth
  • [SOLID STATE STORAGE] - This Dell Computer setup comes with an ultra-fast 1TB Solid State Drive (SSD); Setup as the primary boot device; Boot and load programs with lightning speed ; Additional expansion available
  • [BUY & OWN WITH CONFIDENCE] - From the world's largest Microsoft Authorized Refurbisher; Quality Guarantee and Free Tech Support; Award-winning Customer Service; | Support Sustainable Business
  • [MODERN HI-SPEED PORTS] - USB 3.0 (x4) | USB 2.0 (x4) | DisplayPort (x1) | HDMI Port (x1) | Audio Combo Jack (x1) | Audio Out (x1) | RJ-45 Ethernet (x1) | Internal SATA (x3)

Separate a missing cache from a Linux dependency failure

Binary absent

npx cypress cache list shows no matching version, or the cache directory does not exist. Restore the path, correct the cache key, remove the script-blocking setting, and run npx cypress install.

Binary present but cannot launch

If the matching version is listed and installation completes, but verification reports a startup or shared-library error, inspect the executable’s dependencies. Cypress troubleshooting documentation recommends using ldd against the Cypress binary to identify libraries reported as “not found.” Install the missing packages in the runner image or use a Cypress-supported browser image, then rerun:

npx cypress cache path
# Locate the versioned executable under that directory, then:
ldd /path/to/Cypress/Cypress
npx cypress verify

Do not “fix” a library error by repeatedly deleting and downloading the same binary; the cache is present, while the host runtime is incomplete.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recovery procedure for an existing pipeline

  1. Read the failing job’s Cypress package version from the lockfile-resolved installation and print npx cypress cache path.
  2. Print npx cypress cache list and confirm that exact version is present.
  3. Remove --ignore-scripts or CYPRESS_INSTALL_BINARY=0 if those settings are accidental. If scripts must remain disabled, retain the setting and add explicit installation.
  4. Set a stable CYPRESS_CACHE_FOLDER at pipeline or job level.
  5. Add that directory to GitLab cache paths in both installation and test jobs.
  6. Run npx cypress install, then npx cypress verify, and preserve the diagnostic output on failure.
  7. Run one cold-cache pipeline and one warm-cache pipeline. The first proves installation works; the second proves restoration works.
  8. If the executable exists but verification fails on a library, use ldd and update the image or system packages.

Performance, reliability and cost considerations

  • Persisting the binary avoids downloading it for every job, which is especially useful when a pipeline fans out to many workers.
  • A project-local cache makes the path visible and portable across users; a home-directory cache can work, but only if every job uses the same home and runner user.
  • Changing Cypress versions should invalidate the cache key. Keeping the lockfile in the key ties the binary cache to the dependency graph.
  • Cache restoration is an optimization, not a correctness guarantee. The pipeline should remain able to reinstall on a miss.
  • Cache only what you need. A dedicated Cypress directory is less fragile than archiving an entire node_modules tree.
  • For private runners, verify that outbound downloads are allowed or that your proxy is configured for the Cypress download URL; expose DEBUG=cypress:cli* when diagnosing network failures.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your CI workflow also needs a rendered screenshot of a page (for example, a visual artifact from an end-to-end check), ScreenshotNeo can capture it through one HTTP request instead of maintaining a separate browser script. Cookie and consent banners, newsletter popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are not billed. Its MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

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

See the ScreenshotNeo documentation for options such as full-page capture, selectors, device presets, custom CSS or JavaScript, waiting rules, headers, cookies, geolocation, PDF output, caching and asynchronous jobs. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

Rank #4
Sale
VIVO Black 32 in Standing Desk Converter, DESK-V000K
  • Create Instant Active Standing - VIVO’s desk riser provides on-demand standing throughout the day for the freedom to get out of your chair and relieve muscle tension, reduce stress, and increase productivity. --Patented--
  • Space Efficient 31.5" Surface - The top surface measures 31.5” x 15.7”, which maximizes space while still providing room for dual monitors. The 31.3" x 11.8" (10.5" in center) keyboard tray raises in sync with the top surface to create a comfortable workstation.
  • Strong 33 lbs Lift Assist - Go from sitting to standing in one smooth motion using the innovative simple touch height locking mechanism (Adjustment Range: 4.5" to 20"). Lift design elevates straight upwards.
  • Very Minimal Assembly - This riser is almost ready to go right out of the box! Place on your existing desk, attach the keyboard tray, and start organizing your workstation.
  • We've Got You Covered - Sturdy, high-grade steel design is backed with a 3-Year Manufacturer Warranty and friendly tech support to help with any questions or concerns.

Common errors and targeted fixes

Symptom Likely cause Fix
“A Cached Cypress Binary Could not be found” immediately after npm ci Postinstall skipped or cache absent Check script policy, run npx cypress install, and cache the binary directory.
Install job passes; test job reports the same error Cache path, key or policy differs between jobs Declare one CYPRESS_CACHE_FOLDER and identical cache paths; inspect restore logs.
Only an old Cypress version appears in cache list Stale key or changed lockfile Use a lockfile-based key and install the currently resolved version.
Install log says scripts are ignored --ignore-scripts or organizational policy Keep the policy if required, then run explicit npx cypress install.
CYPRESS_INSTALL_BINARY=0 is present Intentional download suppression Unset it for this job or provide the binary through a controlled cache/image.
Binary exists; verification reports missing libraries Linux runtime dependency failure Run ldd on the executable and add the missing libraries or change the image.
Permission denied under the cache Different runner user or unwritable directory Use a project-local path and ensure the job user can read and execute it.

FAQ

Does npm ci always download Cypress?

No. It normally triggers Cypress’s postinstall download, but lifecycle scripts can be disabled, and an explicit CYPRESS_INSTALL_BINARY=0 prevents it.

Should I delete the Cypress cache on every run?

No. Deleting it removes the speed and reliability benefit of persistence. Invalidate it when the Cypress version changes or when the cache is demonstrably corrupt.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can a Docker image replace GitLab caching?

Yes, an image can contain the required binary and dependencies, but your pipeline still needs a consistent installation strategy. A cache-backed install step remains useful when versions change.

Why does the same YAML work on one runner but not another?

Runners can differ in executor, user, network access, filesystem permissions, cache availability and installed Linux libraries. Print the path and version in each environment before comparing results.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.