Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If GitHub Actions fails at npm ci with ERESOLVE unable to resolve dependency tree or Conflicting peer dependency, identify the packages and incompatible peer-version range in the full npm error, then align the dependency versions and commit a regenerated lockfile. Make the CI install use the same Node version and npm settings used to create that lockfile. The Cypress GitHub Action can run Cypress, but it cannot make incompatible npm peer requirements compatible.
What an ERESOLVE peer conflict means
npm is refusing to construct the dependency tree because a package declares a peer dependency range that conflicts with the version installed or selected elsewhere in the tree. This is an installation problem, before Cypress tests or browser execution begin. npm documents that conflicting peer dependencies can cause installation to fail, while --legacy-peer-deps changes how npm handles those peers: npm ci documentation.
Start with the first failing command and its complete error report. Do not assume that the Cypress Action, a browser, or a Cypress binary is at fault just because the job is a Cypress workflow.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Read the npm error before changing the workflow
- Find the lines naming the package that requires a peer, the peer package, the installed or selected version, and the required range. npm’s report commonly distinguishes the package’s declared requirement from the version it found.
- Check the corresponding entries in
package.jsonand the committed lockfile. Also inspect recent dependency changes, including upgrades to plugins or frameworks that declare Cypress or another package as a peer. - Confirm which install command failed. An
ERESOLVEduringnpm ciis different from a later failure to download Cypress’s binary or launch a browser. - Record the Node version and npm configuration used locally and in CI. Differences can expose mismatches or make an install that depends on special flags fail in Actions.
A message such as “npm ci works locally but fails in GitHub Actions” is a useful symptom description, not proof that GitHub Actions is resolving packages differently. Compare the actual runtime versions, working directory, lockfile, command, and configuration before changing the workflow.
#1 Best Overall
Fix the dependency tree and lockfile
Preferred fix: choose compatible package versions
Choose versions whose declared peer ranges overlap and that are supported by your project. Update the manifest, then regenerate the lockfile with the project’s intended npm version and configuration. Review the lockfile diff and commit it together with the manifest changes. In CI, use npm ci to install from that committed lockfile.
This resolves the underlying constraint rather than hiding it. Do not reflexively delete package-lock.json, use --force, or change the workflow before understanding which packages disagree. If regenerating the lockfile changes many unrelated versions, review the diff carefully and avoid committing unexplained dependency churn.
When a peer bypass is an intentional temporary choice
--legacy-peer-deps tells npm to ignore peer dependencies when constructing the tree. It may permit an install where strict peer resolution fails, but it does not establish that the selected packages work together at runtime. Use it only when the combination has been deliberately accepted and tested, and document the reason and an owner or plan for removing the bypass.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsLockfile creation and CI installation must use consistent dependency-tree-shaping options. npm specifically warns: “If you create your package-lock.json file by running npm install with flags that can affect the shape of the dependency tree, such as –legacy-peer-deps or –install-links, you must provide the same flags to npm ci or you are likely to encounter errors.” One way to persist a project-wide choice is a committed project .npmrc containing:
legacy-peer-deps=trueUse that only if the bypass is intended for every install in that project. Otherwise, make the choice explicit in the commands and ensure the lockfile was created with matching settings. Avoid treating --force as a routine alternative: it suppresses safeguards without resolving the incompatibility.
Make GitHub Actions reproduce the repository install
GitHub recommends using actions/setup-node, committing the package lockfile, and using npm ci for npm CI installs. Cypress’s official action supports installation and caching as part of a Cypress workflow, but it does not remove incompatible peer constraints from the application’s dependency tree. See Cypress’s GitHub Actions guide, GitHub’s Node.js build and test guide, and setup-node’s cache guidance.
Adapt this pattern to your repository. Replace the action version placeholders with deliberately selected versions, and choose a Node version supported by the project and its dependencies. The Cypress action is shown after the explicit clean install so that npm’s install failure is easy to identify.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
steps:
- uses: actions/checkout@<chosen-version>
- uses: actions/setup-node@<chosen-version>
with:
node-version: '<project-supported-version>'
cache: npm
# Set cache-dependency-path when the lockfile is not at repository root.
- run: npm ci
- uses: cypress-io/github-action@v7
with:
# Configure build/start options as appropriate for this repository.
command: npx cypress runThe example intentionally does not prescribe a Node release: use the version the project supports rather than copying a number from an unrelated example. Cypress recommends the latest major action line and also documents pinning a specific release as a way to mitigate unforeseen breaks; check the action documentation for inputs supported by the version you choose.
Monorepos and non-root lockfiles
Run the install in the directory containing the intended package.json and lockfile. In a monorepo, set the job or step working directory as appropriate and point setup-node’s cache-dependency-path to the relevant lockfile. A cache keyed to the wrong lockfile does not make the install reproducible and can conceal that the job is installing a different project than expected.
Keep caches and Cypress binary failures separate
A stale cache is not the first explanation for an npm peer-range ERESOLVE: the error describes incompatible dependency requirements. GitHub’s setup-node cache is for package-manager data, while Cypress also has a binary cache. Cypress advises against caching node_modules directly because this bypasses package-manager reconstruction and integrity behavior and can contribute to Cypress binary installation problems. See Cypress CI guidance.
If the log instead indicates the Cypress package’s postinstall was skipped or its platform binary is missing, follow the separate binary-install path. Cypress documents that the npm package’s postinstall downloads the binary; check the Cypress cache and, if the needed binary is absent, run:
npx cypress installThat command addresses a missing Cypress binary, not npm’s peer dependency resolution. Likewise, browser availability and a test failure after installation are later-stage issues; fix the first failing stage rather than applying a remedy for a different error.
Troubleshooting common failure patterns
ERESOLVE unable to resolve dependency tree
Cause: a package’s peer range does not accept the version npm is selecting. Fix: identify both packages and their ranges in the report, select compatible package versions, regenerate and commit the lockfile, and rerun npm ci.
“Conflicting peer dependency” appears after an upgrade
Cause: the upgraded package or one of its peers has a requirement that conflicts with the rest of the project. Fix: inspect the upgrade’s declared peer requirements and choose a compatible set of versions. Do not infer that the Cypress Action should be changed unless its own configuration is the actual failing point.
npm ci rejects the lockfile or behaves differently in CI
Cause: the lockfile may not match the manifest, the job may be using another directory or lockfile, or lockfile creation may have used options that CI does not use. Fix: check out the intended committed lockfile, run in its package directory, and make npm version and relevant configuration consistent. If a dependency-tree-shaping option was used to create the lockfile, npm requires the same option for npm ci; a committed project .npmrc can persist the setting.
Only GitHub Actions fails
Cause: local and CI environments may differ in Node version, npm configuration, working directory, install command, or lockfile. Fix: compare those inputs directly and configure actions/setup-node with the project’s supported Node version. Keep the committed lockfile and install command consistent rather than deleting the lockfile to make one environment pass.
The job installs packages but Cypress cannot find its binary
Cause: the Cypress binary download may have been skipped or the binary cache may not contain the required binary. Fix: follow Cypress’s binary diagnostics, check its cache, and run npx cypress install if needed. This is separate from an earlier npm ERESOLVE.
The install works only with --legacy-peer-deps
Cause: strict peer resolution still finds incompatible declared requirements. Fix: prefer aligning versions. If the bypass is deliberately retained, test the resulting package combination, make lockfile creation and CI use the same setting, and record the compatibility risk and removal plan.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If the task is to capture a page rather than run Cypress tests, ScreenshotNeo offers a one-request website screenshot API and an MCP server for AI agents. It accepts and removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. AI agents can use its MCP tools to take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
For example, save a screenshot of Stripe as WebP with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. Learn more at ScreenshotNeo, or sign up for 1,000 free screenshots a month, with no card required.
Choose a fix that remains reproducible
Before merging, verify that the selected package versions satisfy their declared peer ranges, the manifest and lockfile are committed together, CI uses the intended Node version and project directory, and the install command matches the lockfile’s configuration. Keep any peer bypass explicit and temporary where possible. If installation succeeds but the workflow still fails, use the first failing Cypress or browser command to continue diagnosis.
Frequently Asked Questions
Does the Cypress GitHub Action fix npm peer dependency conflicts?
No. It helps install, cache, and run Cypress in GitHub Actions, but it does not change incompatible peer requirements in the application’s dependency tree.
Should I delete package-lock.json when npm ci fails in Actions?
Not as a routine fix. Identify the conflicting requirements, reconcile versions, regenerate the lockfile intentionally, and commit the reviewed manifest and lockfile changes.
Is an npm ERESOLVE error the same as a missing Cypress binary?
No. ERESOLVE is dependency-tree resolution during installation; a missing Cypress binary is a separate postinstall or cache issue.
Quick Recap
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.
