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

If GitLab CI reports “A Cached Cypress Binary could not be found”, the Cypress npm package is present but the platform-specific Cypress application is not available in the cache that the job is using. Check the cache path and installed version, run npx cypress install explicitly when lifecycle scripts were skipped, and persist one consistent cache directory between installation and test jobs. A cached node_modules directory alone is not a dependable replacement for the Cypress binary cache.

What the missing-binary error means

Cypress consists of two separately installed parts: the package resolved by npm, Yarn, pnpm or Bun, and the Cypress application binary downloaded by that package’s lifecycle hook. The command-line package can therefore be listed in node_modules while its matching executable is absent from the global or project cache. Cypress documents this condition as occurring when cypress run or cypress verify is invoked without a valid binary cache (Cypress error messages).

Typical causes are an install command that ignored lifecycle scripts, an explicit CYPRESS_INSTALL_BINARY=0, a cache that was not restored or saved, different cache paths in different jobs, or a cache containing another Cypress version. A binary that exists but will not start is a different problem: investigate Linux shared-library and runtime dependencies instead of repeatedly downloading it.

Diagnose the job before changing the pipeline

1. Print the cache path and installed versions

Run these commands in the same GitLab job that fails:

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.
#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
npx cypress verify

On Linux, Cypress normally uses ~/.cache/Cypress. The list should contain the version required by the installed Cypress package. If the path is empty, points at an unexpected home directory, or lists only older versions, the job has no usable binary.

2. Check the package-manager install policy

Inspect the install command and environment for lifecycle-script suppression:

  • npm or another manager invoked with --ignore-scripts;
  • organization policy that blocks package install scripts;
  • CYPRESS_INSTALL_BINARY=0 set globally or in GitLab variables;
  • a cached node_modules tree restored without running the package manager again.

Cypress’s install documentation explains that the package’s postinstall hook downloads the binary. If that hook is intentionally or accidentally disabled, perform an explicit install after dependencies are available (install Cypress with npm, Yarn, pnpm or Bun).

Repair the binary in a single job

Explicit installation

Add the install command after your dependency installation:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
npm ci
npx cypress install
npx cypress verify
npx cypress run

If the download or extraction fails, expose Cypress CLI diagnostics:

DEBUG=cypress:cli* npx cypress install

Use the equivalent package-manager prefix when your project uses Yarn, pnpm or Bun. The command-line reference documents install and verify (Cypress CLI).

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.

When the binary is intentionally skipped

If your pipeline sets CYPRESS_INSTALL_BINARY=0 to defer downloads, keep that setting only for jobs that do not run Cypress. Remove or override it in the install and test jobs, then run npx cypress install explicitly. Do not assume that a successful npm ci proves the binary was downloaded.

Persist the Cypress cache across GitLab jobs

Separate install and test jobs must use the same cache directory. A stable project-local directory makes the path visible and avoids differences in runner home directories. Cypress’s GitLab example uses a shared CYPRESS_CACHE_FOLDER and caches the resulting directory (Run Cypress in GitLab CI).

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
stages:
  - install
  - test

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

cache:
  key:
    files:
      - package-lock.json
  paths:
    - cache/Cypress/
  policy: pull-push

install:
  stage: install
  image: cypress/browsers:latest
  script:
    - npm ci
    - npx cypress install
    - npx cypress verify
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

test:
  stage: test
  image: cypress/browsers:latest
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - cache/Cypress/
    policy: pull
  script:
    - npx cypress verify
    - npx cypress run

The example is a pattern, not a guarantee for every runner, executor or image. Confirm that the install job saves the directory and that the test job restores the identical path. If you override the default, CYPRESS_CACHE_FOLDER must be present when both cypress install and cypress run execute. Cache keys should change when the lockfile or Cypress version changes; otherwise a stale cache can be restored.

Cache policy and job ordering

  • Use a writable path inside the project when runner home directories are not stable.
  • Let the installation job populate the cache; use a pull-only policy in test jobs when appropriate.
  • Make sure a job that only restores a cache does not accidentally overwrite it with an empty directory.
  • Keep the package-manager cache and Cypress binary cache conceptually separate.

Why caching node_modules is not enough

Cypress cautions that directly caching node_modules can bypass package-manager checks and leave the binary postinstall step skipped (Continuous Integration with Cypress). Cache the package manager’s download data and the Cypress binary directory instead. If you already restored node_modules, run the explicit install command and verify the resulting cache rather than trusting the restored directory.

Distinguish a missing binary from a Linux dependency failure

npx cypress cache list should show the required version before you investigate the host. If the version is present but verify reports that the executable cannot launch, inspect operating-system prerequisites and shared libraries. Cypress’s troubleshooting guidance recommends running ldd against the Cypress executable to identify missing libraries (Troubleshooting Cypress).

These symptoms point to a dependency problem rather than a cache problem:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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)
  • the expected version is listed in the cache;
  • the failure names a missing shared object or display/runtime library;
  • the executable starts in one image but not another.

Use a Cypress-supported browser image or install the libraries required by your Linux distribution, then rerun npx cypress verify. Re-downloading the same binary will not supply missing host libraries.

Common GitLab CI failure modes

“It works locally but not in CI”

Your local machine may have a populated user cache while the ephemeral runner starts empty. Print npx cypress cache path in CI, install explicitly, and cache that path.

“The install job succeeds, but the test job cannot find it”

The jobs probably use different HOME values, cache paths, keys or cache policies. Set CYPRESS_CACHE_FOLDER globally and list the same directory under cache.paths in both jobs.

“A cache exists, but Cypress wants another version”

Compare npx cypress cache list with the version resolved from your lockfile. Invalidate the stale cache by changing the key, run npm ci and npx cypress install, then save the new directory.

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

“The download is blocked or times out”

Run DEBUG=cypress:cli* npx cypress install and inspect proxy, firewall, certificate and runner-network settings. A failed download is not repaired by changing test specs. Once one job downloads successfully, persist the binary cache so later jobs do not repeat the transfer.

“The cache is restored but is empty after the job”

Check the path printed by Cypress against the path GitLab archives. A relative path such as cache/Cypress must resolve under $CI_PROJECT_DIR; a cache entry for ~/.cache/Cypress will not capture a project-local override.

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.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Performance, reliability and security considerations

The Cypress binary is substantially larger than ordinary JavaScript dependencies, so persistence reduces repeated downloads and shortens later jobs. Cache the binary independently of test artifacts, key it by the lockfile or Cypress version, and verify after restoration. Do not place secrets in cache paths or archive generated configuration containing credentials. Treat shared caches as reusable build data, not as a substitute for dependency integrity checks.

For reproducible pipelines, pin the Cypress version in the lockfile, use the same major browser image across jobs, and keep install and test commands explicit. When changing Cypress versions, allow the cache key to change so the new binary is downloaded instead of relying on an incompatible older entry.

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

Or skip the browser setup

If your task is simply to obtain a clean webpage image rather than run Cypress tests, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF; it accepts cookie/consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.

For a direct capture, see the ScreenshotNeo API documentation:

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

ScreenshotNeo also supports custom viewport and device settings, full-page and CSS-selector captures, dark mode, retina scale, PDFs, custom CSS and JavaScript, clicks, wait conditions, blocking rules, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk requests and a usage API. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.

The Free plan includes 1,000 screenshots per month without a card. Paid plans start at $5 for 3,000 shots; yearly billing provides two months free, and every feature is available on every plan. Create a free ScreenshotNeo account.

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

Verification checklist

  • npx cypress cache path prints the intended directory.
  • npx cypress cache list includes the project’s installed version.
  • No install policy or CYPRESS_INSTALL_BINARY=0 is suppressing the download.
  • npx cypress install completes, with debug output enabled if it does not.
  • The exact cache directory is listed in GitLab configuration for install and test jobs.
  • npx cypress verify succeeds after restoration.
  • If verification reaches the executable but fails to launch, Linux libraries are being checked separately.

FAQ

Does npm install always download Cypress?

Normally the package lifecycle hook downloads the binary, but ignored or blocked scripts and CYPRESS_INSTALL_BINARY=0 prevent that. Run npx cypress install explicitly when scripts are unavailable.

Should I commit the Cypress binary to the repository?

No. Install it in CI and persist the documented cache directory through GitLab’s cache mechanism.

What command proves the binary is usable?

Run npx cypress verify after installation or cache restoration. A successful cache listing alone does not test whether the executable can launch on the runner.

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.

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